fimo 0.7.0-experimental.1 → 0.7.0-experimental.10

package/dist/scripts/apply-wrap.js

@@ -0,0 +1,278 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { scanWrappable } from './scan-wrappable.js';
+/**
+ * The --apply codemod: performs the PROVABLY-SAFE wrap transforms
+ * deterministically, leaving every judgment call to the agent.
+ *
+ * In scope:  plain JSX text -> FimoText, <img src="literal"> -> FimoMediaImage,
+ *            <a href="/file.pdf"> -> FimoFileLink.
+ * Out of scope (agent work): attributes (useLabels crosses the RSC boundary),
+ *            formatted text (marks -> FimoRichTextBlock), next/image <Image>
+ *            (framework-specific props), collections, layout wiring.
+ *
+ * Correctness is enforced by the gates, not assumed: the render-parity
+ * baseline is captured BEFORE applying, and `fimo migrate wrap --check`
+ * verifies the result like any other actor's work.
+ */
+/** Elements whose children cannot contain a <span> wrapper. */
+const NO_ELEMENT_CHILDREN = new Set(['option', 'title', 'textarea', 'script', 'style', 'select']);
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+// JSX text carries HTML entities (&apos;, &amp;, …). The FALLBACK keeps the
+// original source form, but the label VALUE is rendered literally by
+// FimoText — seeding the raw entity re-escapes it on screen (the remix
+// dogfood shipped "What&apos;s next?"). Decode when generating values.
+const JSX_ENTITIES = {
+    '&amp;': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+    '&nbsp;': ' ',
+    '&copy;': '©',
+};
+export function decodeJsxEntities(text) {
+    return text
+        .replace(/&(amp|lt|gt|quot|apos|nbsp|copy);/g, (entity) => JSX_ENTITIES[entity] ?? entity)
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)));
+}
+/** Deterministic scope from the file path: app/about/page.tsx -> about. */
+export function keyScope(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const appMatch = normalized.match(/(?:^|\/)app\/(.*)\/?page\.[jt]sx?$/);
+    if (appMatch) {
+        const dir = appMatch[1].replace(/\/$/, '');
+        if (!dir) {
+            return 'home';
+        }
+        const segments = dir
+            .split('/')
+            .filter((segment) => !segment.startsWith('(') && !segment.startsWith('@'))
+            .map((segment) => segment.replace(/^\[+|\]+$/g, '').replace(/^\.\.\./, ''));
+        return segments.join('.') || 'home';
+    }
+    if (/(?:^|\/)app\/layout\.[jt]sx?$/.test(normalized)) {
+        return 'layout';
+    }
+    const stem = basename(normalized).replace(/\.[jt]sx?$/, '');
+    return slugify(stem) || 'shared';
+}
+export function slugify(text) {
+    return collapse(text)
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .split('-')
+        .slice(0, 4)
+        .join('-');
+}
+export class KeyAllocator {
+    used = new Set();
+    constructor(existing) {
+        for (const key of existing) {
+            this.used.add(key);
+        }
+    }
+    allocate(scope, slug) {
+        const base = `${scope}.${slug || 'item'}`;
+        let candidate = base;
+        let counter = 2;
+        while (this.used.has(candidate)) {
+            candidate = `${base}-${counter++}`;
+        }
+        this.used.add(candidate);
+        return candidate;
+    }
+}
+/**
+ * Merge the fimo/next import with an existing one, or insert a new one AFTER
+ * the last import statement — positioned via the AST, never line matching
+ * (a multiline `import {\n …` opening line is not the end of the imports,
+ * as a real portfolio migration proved).
+ */
+export function ensureFimoImport(code, specifiers, importModule = 'fimo/next') {
+    if (specifiers.length === 0) {
+        return code;
+    }
+    const moduleRe = importModule.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+    const importMatch = code.match(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*(['\"])${moduleRe}\\2\\s*;?`));
+    if (importMatch) {
+        const existing = importMatch[1]
+            .split(',')
+            .map((token) => token.trim())
+            .filter(Boolean);
+        const merged = [...new Set([...existing, ...specifiers])].sort();
+        return code.replace(importMatch[0], `import { ${merged.join(', ')} } from "${importModule}";`);
+    }
+    const statement = `import { ${[...new Set(specifiers)].sort().join(', ')} } from "${importModule}";`;
+    let insertAt = 0;
+    try {
+        const program = parseSync('module.tsx', code).program;
+        for (const node of program.body ?? []) {
+            if (node.type === 'ImportDeclaration') {
+                insertAt = node.end;
+            }
+        }
+    }
+    catch {
+        insertAt = 0;
+    }
+    if (insertAt === 0) {
+        return `${statement}\n${code}`;
+    }
+    return `${code.slice(0, insertAt)}\n${statement}${code.slice(insertAt)}`;
+}
+export function applyWrapToFile(code, items, allocator, importModule = 'fimo/next') {
+    const applied = [];
+    const skipped = [];
+    const labels = {};
+    const edits = [];
+    const specifiers = new Set();
+    for (const item of items) {
+        const span = item.span;
+        if (!span) {
+            skipped.push({ item, reason: 'no span info' });
+            continue;
+        }
+        const scope = keyScope(item.file);
+        if (item.kind === 'text') {
+            if (span.parentTag && NO_ELEMENT_CHILDREN.has(span.parentTag.toLowerCase())) {
+                skipped.push({ item, reason: `<${span.parentTag}> cannot contain a wrapper element` });
+                continue;
+            }
+            const raw = code.slice(span.start, span.end);
+            const core = raw.trim();
+            if (!core) {
+                skipped.push({ item, reason: 'whitespace only' });
+                continue;
+            }
+            const lead = raw.slice(0, raw.indexOf(core));
+            const trail = raw.slice(raw.indexOf(core) + core.length);
+            const id = allocator.allocate(scope, slugify(core));
+            edits.push({
+                start: span.start,
+                end: span.end,
+                replacement: `${lead}<FimoText id="${id}">${core}</FimoText>${trail}`,
+            });
+            specifiers.add('FimoText');
+            labels[id] = decodeJsxEntities(collapse(core));
+            applied.push({ kind: 'text', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        if (item.kind === 'image') {
+            if (span.openNameStart === undefined ||
+                span.openNameEnd === undefined ||
+                code.slice(span.openNameStart, span.openNameEnd) !== 'img') {
+                skipped.push({ item, reason: 'next/image and custom components stay agent work' });
+                continue;
+            }
+            const id = allocator.allocate(scope, slugify(basename(item.preview).replace(/\.[a-z0-9]+$/i, '')));
+            edits.push({
+                start: span.openNameStart,
+                end: span.openNameEnd,
+                replacement: `FimoMediaImage id="${id}"`,
+            });
+            specifiers.add('FimoMediaImage');
+            applied.push({ kind: 'image', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        if (item.kind === 'file-link') {
+            if (span.openNameStart === undefined ||
+                span.openNameEnd === undefined ||
+                span.closeNameStart === undefined ||
+                span.closeNameEnd === undefined) {
+                skipped.push({ item, reason: 'self-closing or unparsable anchor' });
+                continue;
+            }
+            const id = allocator.allocate(scope, slugify(basename(item.preview).replace(/\.[a-z0-9]+$/i, '')));
+            edits.push({ start: span.openNameStart, end: span.openNameEnd, replacement: `FimoFileLink id="${id}"` });
+            edits.push({ start: span.closeNameStart, end: span.closeNameEnd, replacement: 'FimoFileLink' });
+            specifiers.add('FimoFileLink');
+            applied.push({ kind: 'file-link', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        skipped.push({ item, reason: `${item.kind} stays agent work` });
+    }
+    let next = code;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) {
+        next = next.slice(0, edit.start) + edit.replacement + next.slice(edit.end);
+    }
+    next = ensureFimoImport(next, [...specifiers], importModule);
+    return { code: next, applied, skipped, labels };
+}
+/**
+ * Apply the safe transforms across the project. Mutates source files and
+ * merges generated labels into `.fimo/migration/labels.json` (never
+ * overwriting existing keys).
+ */
+/** Recorded coverage exemptions the codemod must NOT wrap — items the user
+ *  deliberately kept out (dev-only UI, OG-image markup, …). Matched by the
+ *  same (file, kind, preview) triple the coverage gate uses, so "record the
+ *  exemption first, then --apply auto-wraps the rest" holds. */
+function readApplyExemptions(rootDir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'manifest.json'), 'utf8'));
+        const raw = manifest?.wrap?.exemptions;
+        return Array.isArray(raw)
+            ? raw.filter((entry) => typeof entry?.file === 'string' &&
+                typeof entry?.kind === 'string' &&
+                typeof entry?.preview === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function applyWrap(rootDir, opts = {}) {
+    const scan = scanWrappable(rootDir, { excludePrefixes: opts.excludePrefixes });
+    const existingLabels = (() => {
+        try {
+            return JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'labels.json'), 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    })();
+    // Honor recorded exemptions: the codemod skips them so the coverage gate's
+    // exemption and the codemod stay consistent — otherwise --apply would wrap
+    // an item the user just exempted and the gate would flag the drift.
+    const exemptions = readApplyExemptions(rootDir);
+    const isExempt = (item) => exemptions.some((exemption) => exemption.file === item.file && exemption.kind === item.kind && exemption.preview === item.preview);
+    const allocator = new KeyAllocator([...Object.keys(existingLabels), ...scan.wrappedIds.labels]);
+    const byFile = new Map();
+    for (const item of scan.items) {
+        if (isExempt(item)) {
+            continue;
+        }
+        const list = byFile.get(item.file) ?? [];
+        list.push(item);
+        byFile.set(item.file, list);
+    }
+    const result = { applied: [], skipped: [], labels: {}, filesChanged: [] };
+    for (const [file, items] of byFile) {
+        const filePath = join(rootDir, file);
+        let code;
+        try {
+            code = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            result.skipped.push(...items.map((item) => ({ item, reason: 'unreadable file' })));
+            continue;
+        }
+        const fileResult = applyWrapToFile(code, items, allocator, opts.importModule ?? 'fimo/next');
+        result.applied.push(...fileResult.applied);
+        result.skipped.push(...fileResult.skipped);
+        Object.assign(result.labels, fileResult.labels);
+        if (fileResult.applied.length > 0) {
+            writeFileSync(filePath, fileResult.code);
+            result.filesChanged.push(file);
+        }
+    }
+    return result;
+}

package/dist/scripts/apply-wrap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/apply-wrap.test.js

@@ -0,0 +1,226 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { applyWrap, ensureFimoImport, keyScope, slugify } from './apply-wrap.js';
+import { scanWrappable } from './scan-wrappable.js';
+let dir;
+const project = (files) => {
+    dir = mkdtempSync(join(tmpdir(), 'apply-wrap-'));
+    for (const [rel, content] of Object.entries(files)) {
+        const full = join(dir, rel);
+        mkdirSync(join(full, '..'), { recursive: true });
+        writeFileSync(full, content);
+    }
+    return dir;
+};
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('keyScope / slugify', () => {
+    it('derives scopes from app-router paths', () => {
+        expect(keyScope('app/page.tsx')).toBe('home');
+        expect(keyScope('app/about/page.tsx')).toBe('about');
+        expect(keyScope('app/(marketing)/pricing/page.tsx')).toBe('pricing');
+        expect(keyScope('app/layout.tsx')).toBe('layout');
+        expect(keyScope('components/Footer.tsx')).toBe('footer');
+    });
+    it('slugifies text deterministically', () => {
+        expect(slugify('To get started, edit the page.tsx file.')).toBe('to-get-started-edit');
+        expect(slugify('Déjà vu!')).toBe('deja-vu');
+    });
+});
+describe('ensureFimoImport', () => {
+    it('inserts after the last import', () => {
+        const out = ensureFimoImport('import x from "y";\n\nconst a = 1;', ['FimoText']);
+        expect(out).toContain('import x from "y";\nimport { FimoText } from "fimo/next";');
+    });
+    it('merges into an existing fimo/next import', () => {
+        const out = ensureFimoImport('import { FimoText } from "fimo/next";\n', ['FimoMediaImage', 'FimoText']);
+        expect(out).toContain('import { FimoMediaImage, FimoText } from "fimo/next";');
+    });
+    it('decodes JSX entities in generated label values (fallback keeps the source form)', async () => {
+        const { applyWrapToFile, KeyAllocator } = await import('./apply-wrap.js');
+        const code = `export default function P() {\n  return <p>What&apos;s next &amp; more?</p>;\n}`;
+        const result = applyWrapToFile(code, [
+            {
+                kind: 'text',
+                file: 'app/page.tsx',
+                line: 2,
+                preview: 'What&apos;s next &amp; more?',
+                span: { start: code.indexOf('What'), end: code.indexOf('?</p>') + 1, parentTag: 'p' },
+            },
+        ], new KeyAllocator([]));
+        const [value] = Object.values(result.labels);
+        expect(value).toBe("What's next & more?");
+        expect(result.code).toContain('What&apos;s next &amp; more?');
+    });
+    it('targets the adapter module of the detected framework, never fimo/next unconditionally', () => {
+        const inserted = ensureFimoImport('const a = 1;', ['FimoText'], 'fimo/remix');
+        expect(inserted).toContain('import { FimoText } from "fimo/remix";');
+        const merged = ensureFimoImport('import { FimoText } from "fimo/remix";\n', ['FimoMediaImage'], 'fimo/remix');
+        expect(merged).toContain('import { FimoMediaImage, FimoText } from "fimo/remix";');
+    });
+});
+describe('applyWrap', () => {
+    it('wraps plain text, images, and file links; leaves judgment items', () => {
+        const cwd = project({
+            'app/page.tsx': `export default function Page() {
+  return (
+    <main>
+      <h1>Ship your site in hours</h1>
+      <img src="/hero.png" alt="Hero" />
+      <a href="/whitepaper.pdf">Download the whitepaper</a>
+      <p>Read <strong>honest numbers</strong> today</p>
+      <input placeholder="Your email" />
+      <select><option>Pick one</option></select>
+    </main>
+  );
+}`,
+        });
+        const result = applyWrap(cwd);
+        const code = readFileSync(join(cwd, 'app/page.tsx'), 'utf8');
+        expect(code).toContain('<FimoText id="home.ship-your-site-in">Ship your site in hours</FimoText>');
+        expect(code).toContain('<FimoMediaImage id="home.hero" src="/hero.png" alt="Hero" />');
+        expect(code).toContain('<FimoFileLink id="home.whitepaper" href="/whitepaper.pdf">');
+        expect(code).toContain('</FimoFileLink>');
+        expect(code).toContain('import { FimoFileLink, FimoMediaImage, FimoText } from "fimo/next";');
+        // Judgment items untouched: option text, attribute, rich-ish fragments.
+        expect(code).toContain('<option>Pick one</option>');
+        expect(code).toContain('placeholder="Your email"');
+        expect(result.skipped.some((entry) => entry.reason.includes('<option>'))).toBe(true);
+        expect(result.skipped.some((entry) => entry.item.kind === 'attribute')).toBe(true);
+        // Labels generated for wrapped text (incl. link text wrapped inside FimoFileLink).
+        expect(result.labels['home.ship-your-site-in']).toBe('Ship your site in hours');
+        // The wrapped file parses again and the safe items are gone.
+        const rescan = scanWrappable(cwd);
+        expect(rescan.items.filter((item) => item.kind === 'image' || item.kind === 'file-link')).toEqual([]);
+        expect(rescan.wrappedIds.media).toEqual(['home.hero']);
+        expect(rescan.wrappedIds.files).toEqual(['home.whitepaper']);
+    });
+    it('is idempotent: a second apply changes nothing', () => {
+        const cwd = project({
+            'app/about/page.tsx': `export default function About() {
+  return <h1>We believe analytics should be readable</h1>;
+}`,
+        });
+        applyWrap(cwd);
+        const once = readFileSync(join(cwd, 'app/about/page.tsx'), 'utf8');
+        const second = applyWrap(cwd);
+        const twice = readFileSync(join(cwd, 'app/about/page.tsx'), 'utf8');
+        expect(twice).toBe(once);
+        expect(second.applied).toEqual([]);
+        expect(second.filesChanged).toEqual([]);
+    });
+    it('skips items recorded as exemptions (exempt-first, then --apply wraps the rest)', () => {
+        const cwd = project({
+            'app/page.tsx': `export default function Page() {
+  return (
+    <main>
+      <h1>Wrap this headline</h1>
+      <p>But keep this dev note verbatim</p>
+    </main>
+  );
+}`,
+            '.fimo/migration/manifest.json': JSON.stringify({
+                wrap: {
+                    exemptions: [
+                        {
+                            file: 'app/page.tsx',
+                            kind: 'text',
+                            preview: 'But keep this dev note verbatim',
+                            reason: 'dev-only note',
+                            status: 'unresolved',
+                        },
+                    ],
+                },
+            }),
+        });
+        const result = applyWrap(cwd);
+        const code = readFileSync(join(cwd, 'app/page.tsx'), 'utf8');
+        // The non-exempt headline is auto-wrapped...
+        expect(code).toContain('<FimoText id="home.wrap-this-headline">Wrap this headline</FimoText>');
+        // ...the exempt item is left byte-for-byte and never labelled.
+        expect(code).toContain('<p>But keep this dev note verbatim</p>');
+        expect(code).not.toContain('FimoText id="home.but-keep');
+        expect(Object.values(result.labels)).not.toContain('But keep this dev note verbatim');
+        expect(Object.values(result.labels)).toContain('Wrap this headline');
+    });
+    it('leaves next/image components to the agent', () => {
+        const cwd = project({
+            'app/page.tsx': `import Image from "next/image";
+export default function Page() {
+  return <Image src="/logo.svg" alt="Logo" width={10} height={10} priority />;
+}`,
+        });
+        const result = applyWrap(cwd);
+        expect(result.applied).toEqual([]);
+        expect(result.skipped.some((entry) => entry.reason.includes('next/image'))).toBe(true);
+        expect(readFileSync(join(cwd, 'app/page.tsx'), 'utf8')).toContain('<Image src="/logo.svg"');
+    });
+    it('preserves surrounding whitespace so rendering stays identical', () => {
+        const cwd = project({
+            'app/page.tsx': `export default function Page() {
+  return (
+    <p>
+      Hello world from Fimo
+    </p>
+  );
+}`,
+        });
+        applyWrap(cwd);
+        const code = readFileSync(join(cwd, 'app/page.tsx'), 'utf8');
+        expect(code).toMatch(/<p>\n      <FimoText id="home\.hello-world-from-fimo">Hello world from Fimo<\/FimoText>\n    <\/p>/);
+    });
+    it('avoids key collisions across duplicate texts', () => {
+        const cwd = project({
+            'app/page.tsx': `export default function Page() {
+  return (
+    <div>
+      <button>Contact us</button>
+      <button>Contact us</button>
+    </div>
+  );
+}`,
+        });
+        const result = applyWrap(cwd);
+        expect(Object.keys(result.labels).sort()).toEqual(['home.contact-us', 'home.contact-us-2']);
+    });
+});
+describe('back-office exclusion', () => {
+    it('never touches excluded sections', () => {
+        const cwd = project({
+            'app/admin/page.tsx': `export default function Admin() {
+  return <h1>Secret admin panel</h1>;
+}`,
+            'app/page.tsx': `export default function Home() {
+  return <h1>Public home</h1>;
+}`,
+        });
+        const result = applyWrap(cwd, { excludePrefixes: ['app/admin'] });
+        expect(readFileSync(join(cwd, 'app/admin/page.tsx'), 'utf8')).not.toContain('FimoText');
+        expect(readFileSync(join(cwd, 'app/page.tsx'), 'utf8')).toContain('FimoText');
+        expect(result.applied.map((entry) => entry.file)).toEqual(['app/page.tsx']);
+    });
+});
+describe('ensureFimoImport with multiline imports', () => {
+    it('inserts after a multiline import statement, never inside it', () => {
+        const code = `import { useEffect } from "react";
+import {
+  AnimatedSpan,
+  Terminal,
+  TypingAnimation,
+} from "@/components/magicui/terminal";
+
+export function X() { return null; }`;
+        const out = ensureFimoImport(code, ['FimoText']);
+        expect(out).toContain('} from "@/components/magicui/terminal";\nimport { FimoText } from "fimo/next";');
+        expect(out.indexOf('import { FimoText }')).toBeGreaterThan(out.indexOf('TypingAnimation'));
+    });
+    it('prepends when the file has no imports', () => {
+        const out = ensureFimoImport('export const x = 1;', ['FimoText']);
+        expect(out.startsWith('import { FimoText } from "fimo/next";\n')).toBe(true);
+    });
+});

package/dist/scripts/cms/discover.d.ts

@@ -0,0 +1,2 @@
+import type { CmsConnector } from './types.js';
+export declare function detectCms(frontendDir: string): CmsConnector | null;

package/dist/scripts/cms/discover.js

@@ -0,0 +1,17 @@
+import { strapiConnector } from './strapi/index.js';
+/**
+ * CMS-connector registry. Add a connector factory here to support a new
+ * headless CMS; each returns its `CmsConnector` when it recognizes the
+ * frontend, or null. First match wins. This is the ONLY CMS-neutral file that
+ * enumerates the supported CMSs (the analogue of `frameworks/discover.ts`).
+ */
+const CONNECTORS = [strapiConnector];
+export function detectCms(frontendDir) {
+    for (const factory of CONNECTORS) {
+        const connector = factory(frontendDir);
+        if (connector) {
+            return connector;
+        }
+    }
+    return null;
+}

package/dist/scripts/cms/example-content.d.ts

@@ -0,0 +1,32 @@
+import type { CmsCollectionSchema } from './types.js';
+/**
+ * Generate example content for a CMS schema WITHOUT connecting to the CMS. The
+ * shapes match `api.importEntries`: media fields are omitted (a fake URL
+ * would render a broken image), references point at the first example of the
+ * target type (`<target>-example-1`) so they resolve against the co-seeded
+ * data, and localized types get per-locale string variance so the per-language
+ * editability is visible in Fimo. This is CMS-neutral: it consumes the mapped
+ * Fimo schema only.
+ */
+export interface ExampleSeed {
+    /** Fimo type name. */
+    readonly name: string;
+    readonly isSingleton: boolean;
+    readonly localized: boolean;
+    /** Entry data rows (slug lives inside data for collections). */
+    readonly rows: Array<Record<string, unknown>>;
+    /** Reference descriptor for `importEntries`. */
+    readonly references: Record<string, {
+        target?: string;
+        targets?: string[];
+        by: 'slug';
+        many?: boolean;
+    }>;
+}
+export interface ExampleOptions {
+    /** Rows per collection type (singletons always get exactly one). */
+    readonly count?: number;
+    /** Locale suffix on string values + the batch locale (for localized types). */
+    readonly locale?: string;
+}
+export declare function generateExampleSeed(schema: CmsCollectionSchema, options?: ExampleOptions): ExampleSeed;

package/dist/scripts/cms/example-content.js

@@ -0,0 +1,108 @@
+const DEFAULT_COUNT = 3;
+function kebabCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .toLowerCase()
+        .replace(/^-+|-+$/g, '');
+}
+function humanize(field) {
+    return field
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .replace(/^\w/, (c) => c.toUpperCase());
+}
+function richTextDoc(text) {
+    return {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text }] }],
+    };
+}
+/** A self-contained placeholder image (inline SVG data-URI) in the media
+ *  envelope shape the wrap runtime already understands — no external host, no
+ *  CSP surprises, so cards/heroes render instead of showing broken images. */
+function placeholderMedia(label) {
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630"><rect width="100%" height="100%" fill="#e5e7eb"/><text x="50%" y="50%" font-family="sans-serif" font-size="44" fill="#9ca3af" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`;
+    return {
+        source: 'local',
+        url: `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`,
+        alt: `${label} placeholder`,
+        width: 1200,
+        height: 630,
+        mime: 'image/svg+xml',
+        name: 'placeholder.svg',
+    };
+}
+/** Deterministic ISO date (no wall clock): 2024-01-01 + (n-1) days. */
+function exampleDate(n) {
+    return new Date(Date.UTC(2024, 0, n)).toISOString().slice(0, 10);
+}
+function exampleReferenceSlug(field) {
+    const targetName = field.target ?? field.targets?.[0];
+    if (!targetName) {
+        return undefined;
+    }
+    const slug = `${kebabCase(targetName)}-example-1`;
+    return field.many ? [slug] : slug;
+}
+export function generateExampleSeed(schema, options = {}) {
+    const locale = options.locale;
+    const localeSuffix = locale ? ` (${locale})` : '';
+    const count = schema.isSingleton ? 1 : Math.max(1, options.count ?? DEFAULT_COUNT);
+    const references = {};
+    const rows = [];
+    for (let i = 1; i <= count; i += 1) {
+        const row = {};
+        if (!schema.isSingleton) {
+            row.slug = `${kebabCase(schema.name)}-example-${i}`;
+        }
+        for (const [field, def] of Object.entries(schema.fields)) {
+            // A connector-supplied example (dynamic zones, components) wins over the
+            // type-driven default — critical for dynamic zones, which must be arrays.
+            if (schema.examples && field in schema.examples) {
+                row[field] = schema.examples[field];
+                continue;
+            }
+            switch (def.type) {
+                case 'string':
+                    row[field] = `${humanize(field)} example ${i}${localeSuffix}`;
+                    break;
+                case 'richtext':
+                    row[field] = richTextDoc(`Example ${humanize(schema.name).toLowerCase()} content ${i}${localeSuffix}.`);
+                    break;
+                case 'number':
+                    row[field] = i;
+                    break;
+                case 'boolean':
+                    row[field] = i % 2 === 1;
+                    break;
+                case 'date':
+                    row[field] = exampleDate(i);
+                    break;
+                case 'json':
+                    row[field] = {};
+                    break;
+                case 'media':
+                    row[field] = placeholderMedia(humanize(field));
+                    break;
+                case 'reference': {
+                    const value = exampleReferenceSlug(def);
+                    if (value !== undefined) {
+                        row[field] = value;
+                        references[field] = {
+                            ...(def.target ? { target: def.target } : {}),
+                            ...(def.targets ? { targets: def.targets } : {}),
+                            by: 'slug',
+                            ...(def.many ? { many: true } : {}),
+                        };
+                    }
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        rows.push(row);
+    }
+    return { name: schema.name, isSingleton: schema.isSingleton, localized: schema.localized, rows, references };
+}

package/dist/scripts/cms/example-content.test.d.ts

@@ -0,0 +1 @@
+export {};