fimo 0.7.0-experimental.3 → 0.7.0-experimental.5

package/dist/scripts/cms/strapi/wiring.d.ts

@@ -0,0 +1,17 @@
+import type { CmsCollectionSchema } from '../types.js';
+/**
+ * Machine-wiring for the native `fimo/strapi` read adapter. From the scaffolded
+ * schemas it derives the Strapi-path → Fimo-type map (+ the singletons) and
+ * emits a tiny repo module that instantiates the Fimo-backed fetch. The
+ * migration then swaps the CMS client's `fetch` for `fimoStrapiFetch` — after
+ * which the whole site reads scaffolded content from Fimo, deterministically.
+ */
+export interface StrapiWiring {
+    /** Strapi REST path segment (pluralName) → Fimo type name. */
+    types: Record<string, string>;
+    /** Fimo type names that are single types. */
+    singletons: string[];
+}
+export declare function strapiWiring(schemas: CmsCollectionSchema[]): StrapiWiring;
+/** Emit the repo module (`fimo-strapi.ts`) that wires the fetch to Fimo. */
+export declare function renderFimoStrapiModule(schemas: CmsCollectionSchema[]): string;

package/dist/scripts/cms/strapi/wiring.js

@@ -0,0 +1,36 @@
+export function strapiWiring(schemas) {
+    const types = {};
+    const singletons = [];
+    for (const schema of schemas) {
+        const pluralName = schema.sourcePath.replace(/^\/+/, '');
+        if (pluralName) {
+            types[pluralName] = schema.name;
+        }
+        if (schema.isSingleton) {
+            singletons.push(schema.name);
+        }
+    }
+    return { types, singletons };
+}
+/** Emit the repo module (`fimo-strapi.ts`) that wires the fetch to Fimo. */
+export function renderFimoStrapiModule(schemas) {
+    const { types, singletons } = strapiWiring(schemas);
+    const typeEntries = Object.entries(types)
+        .map(([pluralName, typeName]) => `  '${pluralName}': '${typeName}',`)
+        .join('\n');
+    return `// AUTO-GENERATED by \`fimo migrate --scaffold-cms\`. Serves this site's Strapi
+// content reads from Fimo (scaffolded example content) through fimo/strapi.
+// The migration points the CMS client's fetch at \`fimoStrapiFetch\`; reads for
+// scaffolded types resolve from Fimo, everything else falls through to Strapi.
+import { createFimoStrapiFetch } from 'fimo/strapi';
+
+// Strapi REST path (pluralName) -> Fimo type name.
+const TYPES: Record<string, string> = {
+${typeEntries}
+};
+
+const SINGLETONS = [${singletons.map((name) => `'${name}'`).join(', ')}];
+
+export const fimoStrapiFetch = createFimoStrapiFetch({ types: TYPES, singletons: SINGLETONS });
+`;
+}

package/dist/scripts/cms/strapi/wiring.test.d.ts

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

package/dist/scripts/cms/strapi/wiring.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { renderFimoStrapiModule, strapiWiring } from './wiring.js';
+const schema = (name, sourcePath, isSingleton = false) => ({
+    name,
+    label: name,
+    isSingleton,
+    localized: false,
+    fields: {},
+    sourceUid: `api::${name.toLowerCase()}.${name.toLowerCase()}`,
+    sourcePath,
+});
+describe('strapiWiring', () => {
+    it('maps pluralName paths to Fimo types and lists singletons', () => {
+        const wiring = strapiWiring([schema('BlogPost', '/blog-posts'), schema('Global', '/globals', true)]);
+        expect(wiring.types).toEqual({ 'blog-posts': 'BlogPost', globals: 'Global' });
+        expect(wiring.singletons).toEqual(['Global']);
+    });
+});
+describe('renderFimoStrapiModule', () => {
+    it('emits a module importing fimo/strapi with the type map + singletons', () => {
+        const src = renderFimoStrapiModule([schema('BlogPost', '/blog-posts'), schema('Global', '/globals', true)]);
+        expect(src).toContain("import { createFimoStrapiFetch } from 'fimo/strapi';");
+        expect(src).toContain("'blog-posts': 'BlogPost',");
+        expect(src).toContain("const SINGLETONS = ['Global'];");
+        expect(src).toContain('export const fimoStrapiFetch = createFimoStrapiFetch({ types: TYPES, singletons: SINGLETONS });');
+    });
+});

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

@@ -0,0 +1,94 @@
+/**
+ * CMS-connector contract. A connector recognizes an external headless CMS
+ * behind a wrapped frontend and reads its content-type definitions into the
+ * neutral Fimo schema shape — WITHOUT connecting to the CMS at runtime.
+ *
+ * The connector seam mirrors the framework-adapter contract: a CMS's name and
+ * quirks live ONLY under `scripts/cms/<cms>/`. Everything above (the registry,
+ * the example-content generator, the orchestrator wiring) is CMS-neutral. A
+ * CMS name appearing in neutral code is a review finding.
+ */
+/** Scalar Fimo field types (see `FieldTypeSchema` in api-contracts). */
+export type FimoScalarType = 'string' | 'richtext' | 'media' | 'number' | 'boolean' | 'date' | 'json';
+export interface FimoScalarField {
+    readonly type: FimoScalarType;
+}
+export interface FimoReferenceField {
+    readonly type: 'reference';
+    /** Single-target reference (Fimo type name). */
+    readonly target?: string;
+    /** Poly-target reference (Fimo type names). */
+    readonly targets?: string[];
+    /** True for to-many relations. */
+    readonly many?: boolean;
+}
+export type FimoFieldDef = FimoScalarField | FimoReferenceField;
+/**
+ * One CMS content type mapped to the Fimo schema shape. `fields` is the exact
+ * pushable `contentType.fields` payload; `name`/`label`/`isSingleton` complete
+ * the `api.createSchema` call.
+ */
+export interface CmsCollectionSchema {
+    /** Fimo type name (PascalCase — deterministic from the CMS singular name). */
+    readonly name: string;
+    /** Human display label. */
+    readonly label: string;
+    /** Strapi singleType → true; collectionType → false. */
+    readonly isSingleton: boolean;
+    /** The CMS marks this type as localized → seed per configured locale. */
+    readonly localized: boolean;
+    readonly fields: Record<string, FimoFieldDef>;
+    /** Pre-computed example values for fields the generic generator can't shape
+     *  from the Fimo field type alone (dynamic zones must be arrays, components
+     *  objects). Keyed by field name; the generator uses these verbatim. */
+    readonly examples?: Record<string, unknown>;
+    /** Source CMS uid for provenance (e.g. `api::blog-post.blog-post`). */
+    readonly sourceUid: string;
+    /** Source REST path (e.g. `/blog-posts`) — informational for later rewire. */
+    readonly sourcePath: string;
+}
+/** What a connector reports about a detected CMS. */
+export interface CmsDetection {
+    /** Connector name, capitalized for the data-source prompt (e.g. `Strapi`). */
+    readonly cms: string;
+    /** Host label recorded in the data-source decision. */
+    readonly host: string;
+    /** Absolute path to the CMS app root when co-located (monorepo), else null. */
+    readonly appDir: string | null;
+    /** Absolute path to the frontend's CMS client module dir (where the fetch
+     *  lives), for machine-wiring the reads to Fimo. Null if not found. */
+    readonly clientDir: string | null;
+    /** Repo-relative files/signals that evidenced the detection. */
+    readonly evidence: string[];
+    /** Locales configured in the CMS, when discoverable (may be empty). */
+    readonly locales: string[];
+}
+export interface CmsConnector {
+    readonly detection: CmsDetection;
+    /**
+     * Read every content-type definition into the Fimo schema shape. Returns an
+     * empty array when the schemas are not locally available (decoupled CMS with
+     * no co-located source) — detection can still surface the source for a
+     * keep-live decision even when schema import is impossible.
+     */
+    readSchemas(): CmsCollectionSchema[];
+    /**
+     * Emit a generic list-read helper (as source text) the agent wires into the
+     * site's LIST views so they render the scaffolded example content from Fimo.
+     * Returns null when the CMS has no such helper. `serverImport` is the
+     * framework's Fimo server subpath (e.g. `fimo/next/server`) the helper imports
+     * `fetchEntries` from.
+     */
+    renderListSource?(schemas: CmsCollectionSchema[], serverImport: string): string | null;
+    /**
+     * Machine-wire the frontend's CMS reads to Fimo: emit the adapter module and
+     * swap the client's fetch, so the whole site reads scaffolded content from
+     * Fimo. Deterministic — no agent step.
+     */
+    wireClient?(cwd: string, schemas: CmsCollectionSchema[]): CmsWireResult;
+}
+export interface CmsWireResult {
+    changes: string[];
+    warnings: string[];
+    wired: boolean;
+}

package/dist/scripts/cms/types.js

@@ -0,0 +1,11 @@
+/**
+ * CMS-connector contract. A connector recognizes an external headless CMS
+ * behind a wrapped frontend and reads its content-type definitions into the
+ * neutral Fimo schema shape — WITHOUT connecting to the CMS at runtime.
+ *
+ * The connector seam mirrors the framework-adapter contract: a CMS's name and
+ * quirks live ONLY under `scripts/cms/<cms>/`. Everything above (the registry,
+ * the example-content generator, the orchestrator wiring) is CMS-neutral. A
+ * CMS name appearing in neutral code is a review finding.
+ */
+export {};

package/dist/scripts/detect-framework.d.ts

@@ -0,0 +1,39 @@
+export type DetectedFramework = 'next' | 'react-router' | 'remix' | 'astro' | 'nuxt' | 'sveltekit' | 'vue' | 'vite';
+export interface FrameworkDetection {
+    framework: DetectedFramework | null;
+    /** For Next.js: the app-router directory (`app` or `src/app`) when present. */
+    appDir?: string;
+    /** For Next.js: the pages-router directory (`pages` or `src/pages`) when present. */
+    pagesDir?: string;
+    /** A recognized framework that wrap migration does not support yet. */
+    unsupported?: string;
+    /** For bare Vite: the project depends on react, so .jsx/.tsx is React JSX. */
+    react?: boolean;
+}
+/**
+ * Detect the framework of an existing site from its package.json and layout.
+ * Used by `fimo init` (adopt-existing-site) and the wrap migration to decide
+ * how routes are discovered and which env flavor to write.
+ */
+export declare function detectFramework(cwd: string): FrameworkDetection;
+/** A frontend app found inside a workspace, adoptable by `fimo init`. */
+export interface AdoptableApp {
+    /** Absolute directory of the app. */
+    dir: string;
+    /** Directory relative to the scan root (for display + as the init dirArg). */
+    relDir: string;
+    detection: FrameworkDetection;
+}
+/**
+ * Find frontend apps to adopt anywhere inside a directory tree. Most real
+ * sites are monorepos where the framework app is NOT at the root and NOT
+ * necessarily under `apps/` (`frontend/`, `sites/web`, `packages/marketing`,
+ * …) — `detectFramework(root)` returns null and `fimo init` would wrongly
+ * scaffold a new project. This walks the tree up to a bounded depth, running
+ * `detectFramework` on every directory that has a package.json and pruning
+ * `node_modules`/build output, so it finds the app wherever it lives without
+ * relying on a naming convention or a workspace manifest. The root itself is
+ * excluded (the caller checks it directly); descent stops at the first
+ * framework match in a subtree (an app's own subdirs are not separate apps).
+ */
+export declare function findAdoptableApps(rootDir: string): AdoptableApp[];

package/dist/scripts/detect-framework.js

@@ -0,0 +1,133 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/**
+ * Detect the framework of an existing site from its package.json and layout.
+ * Used by `fimo init` (adopt-existing-site) and the wrap migration to decide
+ * how routes are discovered and which env flavor to write.
+ */
+export function detectFramework(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return { framework: null };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return { framework: null };
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) {
+        const appDir = ['app', 'src/app'].find((dir) => existsSync(join(cwd, dir)));
+        const pagesDir = ['pages', 'src/pages'].find((dir) => existsSync(join(cwd, dir)));
+        return { framework: 'next', appDir, pagesDir };
+    }
+    if (deps['react-router'] || deps['@react-router/dev']) {
+        return { framework: 'react-router' };
+    }
+    if (deps['@remix-run/react']) {
+        const pagesDir = ['app/routes'].find((dir) => existsSync(join(cwd, dir)));
+        return { framework: 'remix', pagesDir };
+    }
+    if (deps.astro) {
+        const pagesDir = ['src/pages'].find((dir) => existsSync(join(cwd, dir)));
+        return { framework: 'astro', pagesDir };
+    }
+    if (deps.nuxt) {
+        // 'src/pages' covers the common custom srcDir (nuxt.config `srcDir: './src'`).
+        const pagesDir = ['pages', 'app/pages', 'src/pages'].find((dir) => existsSync(join(cwd, dir)));
+        return { framework: 'nuxt', pagesDir };
+    }
+    if (deps['@sveltejs/kit']) {
+        const pagesDir = ['src/routes'].find((dir) => existsSync(join(cwd, dir)));
+        return { framework: 'sveltekit', pagesDir };
+    }
+    if (deps.vue && deps.vite) {
+        return { framework: 'vue' };
+    }
+    if (deps.vite) {
+        // A react dependency guarantees the JSX runtime: the --apply codemod and
+        // react-router route discovery are safe. Bare vite (Solid, Preact, lit)
+        // stays hands-off.
+        return { framework: 'vite', react: Boolean(deps.react) };
+    }
+    // Known frameworks we can NAME but not wrap yet — lets `fimo init` route
+    // honestly instead of silently falling through to create-new.
+    const unsupportedByDep = [
+        ['gatsby', 'Gatsby'],
+        ['@angular/core', 'Angular'],
+        ['@docusaurus/core', 'Docusaurus'],
+        ['@11ty/eleventy', 'Eleventy'],
+    ];
+    for (const [dep, name] of unsupportedByDep) {
+        if (deps[dep]) {
+            return { framework: null, unsupported: name };
+        }
+    }
+    return { framework: null };
+}
+const WORKSPACE_SKIP = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.turbo',
+    '.vercel',
+    'coverage',
+]);
+/** How deep below the root the scan looks for a framework app (`apps/ui` is
+ *  depth 2, `packages/frontend/web` is depth 3). */
+const MAX_SCAN_DEPTH = 3;
+/**
+ * Find frontend apps to adopt anywhere inside a directory tree. Most real
+ * sites are monorepos where the framework app is NOT at the root and NOT
+ * necessarily under `apps/` (`frontend/`, `sites/web`, `packages/marketing`,
+ * …) — `detectFramework(root)` returns null and `fimo init` would wrongly
+ * scaffold a new project. This walks the tree up to a bounded depth, running
+ * `detectFramework` on every directory that has a package.json and pruning
+ * `node_modules`/build output, so it finds the app wherever it lives without
+ * relying on a naming convention or a workspace manifest. The root itself is
+ * excluded (the caller checks it directly); descent stops at the first
+ * framework match in a subtree (an app's own subdirs are not separate apps).
+ */
+export function findAdoptableApps(rootDir) {
+    const apps = [];
+    const walk = (dir, depth) => {
+        if (depth > MAX_SCAN_DEPTH) {
+            return;
+        }
+        if (dir !== rootDir && existsSync(join(dir, 'package.json'))) {
+            const detection = detectFramework(dir);
+            if (detection.framework) {
+                apps.push({ dir, relDir: relative(rootDir, dir), detection });
+                return; // don't descend into an app's own subtree
+            }
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() && !WORKSPACE_SKIP.has(entry.name) && !entry.name.startsWith('.')) {
+                walk(join(dir, entry.name), depth + 1);
+            }
+        }
+    };
+    walk(rootDir, 0);
+    // Shallower + apps/-conventional first (the most likely primary site), then
+    // alphabetical — the order the interactive picker presents them in.
+    return apps.sort((a, b) => {
+        const depthA = a.relDir.split('/').length;
+        const depthB = b.relDir.split('/').length;
+        const rank = (relDir) => (relDir.startsWith('apps/') ? 0 : 1);
+        return rank(a.relDir) - rank(b.relDir) || depthA - depthB || a.relDir.localeCompare(b.relDir);
+    });
+}

package/dist/scripts/detect-framework.test.d.ts

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

package/dist/scripts/detect-framework.test.js

@@ -0,0 +1,122 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { detectFramework } from './detect-framework.js';
+let dir;
+const project = (deps, dirs = []) => {
+    dir = mkdtempSync(join(tmpdir(), 'detect-framework-'));
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 't', dependencies: deps }));
+    for (const d of dirs) {
+        mkdirSync(join(dir, d), { recursive: true });
+    }
+    return dir;
+};
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('detectFramework', () => {
+    it('detects next with the app dir', () => {
+        expect(detectFramework(project({ next: '^15.0.0' }, ['app']))).toEqual({ framework: 'next', appDir: 'app' });
+        expect(detectFramework(project({ next: '^15.0.0' }, ['src/app']))).toEqual({
+            framework: 'next',
+            appDir: 'src/app',
+        });
+    });
+    it('detects react-router and vite', () => {
+        expect(detectFramework(project({ 'react-router': '^7.0.0' })).framework).toBe('react-router');
+        expect(detectFramework(project({ vite: '^7.0.0' })).framework).toBe('vite');
+    });
+    it('prefers next over an incidental vite dep', () => {
+        expect(detectFramework(project({ next: '^15.0.0', vite: '^7.0.0' }, ['app'])).framework).toBe('next');
+    });
+    it('returns null without a package.json or known framework', () => {
+        expect(detectFramework(join(tmpdir(), 'nope-does-not-exist')).framework).toBeNull();
+        expect(detectFramework(project({ express: '^4.0.0' })).framework).toBeNull();
+    });
+});
+describe('unsupported framework naming', () => {
+    it('names still-unsupported frameworks; astro is now adoptable', async () => {
+        const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const dir = mkdtempSync(join(tmpdir(), 'detect-'));
+        try {
+            writeFileSync(join(dir, 'package.json'), JSON.stringify({ dependencies: { gatsby: '^5.0.0' } }));
+            const { detectFramework } = await import('./detect-framework.js');
+            expect(detectFramework(dir)).toEqual({ framework: null, unsupported: 'Gatsby' });
+            writeFileSync(join(dir, 'package.json'), JSON.stringify({ dependencies: { astro: '^5.0.0' } }));
+            expect(detectFramework(dir).framework).toBe('astro');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe('findAdoptableApps (monorepo / nested detection)', () => {
+    const workspace = (files) => {
+        dir = mkdtempSync(join(tmpdir(), 'find-apps-'));
+        for (const [rel, content] of Object.entries(files)) {
+            const full = join(dir, rel);
+            mkdirSync(join(full, '..'), { recursive: true });
+            writeFileSync(full, content);
+        }
+        return dir;
+    };
+    const pkg = (deps) => JSON.stringify({ name: 'x', dependencies: deps });
+    it('finds a Next app nested under apps/ when the root has no framework', async () => {
+        const { findAdoptableApps } = await import('./detect-framework.js');
+        const root = workspace({
+            'package.json': JSON.stringify({ name: 'monorepo', workspaces: ['apps/*'] }),
+            'apps/ui/package.json': pkg({ next: '^15.0.0' }),
+            'apps/ui/app/page.tsx': 'export default () => null;',
+            'apps/strapi/package.json': pkg({ '@strapi/strapi': '^5.0.0' }),
+        });
+        const apps = findAdoptableApps(root);
+        expect(apps.map((a) => a.relDir)).toEqual(['apps/ui']);
+        expect(apps[0].detection.framework).toBe('next');
+        expect(apps[0].detection.appDir).toBe('app');
+    });
+    it('finds an app in a NON-conventional dir (frontend/web), 3 levels deep', async () => {
+        const { findAdoptableApps } = await import('./detect-framework.js');
+        const root = workspace({
+            'package.json': JSON.stringify({ name: 'r', private: true }),
+            'frontend/web/package.json': pkg({ astro: '^5.0.0' }),
+        });
+        const apps = findAdoptableApps(root);
+        expect(apps.map((a) => a.relDir)).toEqual(['frontend/web']);
+        expect(apps[0].detection.framework).toBe('astro');
+    });
+    it('returns several apps for the picker, apps/ first', async () => {
+        const { findAdoptableApps } = await import('./detect-framework.js');
+        const root = workspace({
+            'package.json': JSON.stringify({ name: 'r' }),
+            'apps/site/package.json': pkg({ next: '^15.0.0' }),
+            'packages/docs/package.json': pkg({ astro: '^5.0.0' }),
+        });
+        const apps = findAdoptableApps(root);
+        expect(apps.map((a) => a.relDir)).toEqual(['apps/site', 'packages/docs']);
+    });
+    it('prunes node_modules and does not descend into a matched app', async () => {
+        const { findAdoptableApps } = await import('./detect-framework.js');
+        const root = workspace({
+            'package.json': JSON.stringify({ name: 'r' }),
+            'apps/web/package.json': pkg({ next: '^15.0.0' }),
+            // a nested example inside the matched app must NOT be returned separately
+            'apps/web/examples/demo/package.json': pkg({ astro: '^5.0.0' }),
+            'node_modules/some-dep/package.json': pkg({ next: '^15.0.0' }),
+        });
+        const apps = findAdoptableApps(root);
+        expect(apps.map((a) => a.relDir)).toEqual(['apps/web']);
+    });
+    it('returns [] when nothing framework-shaped is found', async () => {
+        const { findAdoptableApps } = await import('./detect-framework.js');
+        const root = workspace({
+            'package.json': JSON.stringify({ name: 'r' }),
+            'apps/api/package.json': pkg({ '@strapi/strapi': '^5.0.0' }),
+        });
+        expect(findAdoptableApps(root)).toEqual([]);
+    });
+});

package/dist/scripts/draft-rows.d.ts

@@ -0,0 +1,19 @@
+import type { SchemaDraft } from './draft-schemas.js';
+import type { WrapScanResult } from './scan-wrappable.js';
+export interface RowsFile {
+    draftUid: string;
+    source: string;
+    references: Record<string, {
+        target?: string;
+        targets?: string[];
+        by: 'slug';
+        many?: boolean;
+    }>;
+    rows: Array<Record<string, unknown>>;
+}
+/**
+ * Stage rows for every draft. Drafts carry the inferred field types, the
+ * scan carries the raw rows (typedRows for in-code candidates; data files
+ * are re-read from disk for the full, untruncated dataset).
+ */
+export declare function writeRowsStaging(rootDir: string, scan: WrapScanResult, drafts: SchemaDraft[]): number;

package/dist/scripts/draft-rows.js

@@ -0,0 +1,135 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+/**
+ * Machine-staged entry ROWS for every drafted collection: the deterministic
+ * transformation agents kept re-implementing by hand (media envelopes,
+ * richtext docs, slugs inside data), applied once by the machine. Reference
+ * fields keep their SOURCE values (slugs/names) and each file carries a
+ * references descriptor — the resolution to documentIds happens at seed
+ * time (agent-side maps today; server-side via the batch endpoint next).
+ *
+ * Output: `.fimo/migration/rows/<ProvisionalUid>.rows.json`
+ *   { draftUid, source, references: { field: { target, by, many? } }, rows }
+ *
+ * Regenerated on every migrate run; `schemas adopt-drafts` rewrites
+ * draftUid and reference targets through the same renames it applies to the
+ * schema files.
+ */
+const MEDIA_PATH = /^\/(images|img|videos|video|media|assets|files|docs|documents)\//i;
+const MEDIA_EXT = /\.(png|jpe?g|gif|webp|avif|svg|mp4|webm|mov|mp3|wav|pdf|zip|docx?)$/i;
+function toRichTextDoc(text) {
+    const paragraphs = text
+        .split(/\n\n+/)
+        .map((paragraph) => paragraph.trim())
+        .filter(Boolean);
+    return {
+        type: 'doc',
+        content: paragraphs.map((paragraph) => ({
+            type: 'paragraph',
+            content: [{ type: 'text', text: paragraph }],
+        })),
+    };
+}
+function transformValue(fieldType, value) {
+    if (value == null) {
+        return value;
+    }
+    if (fieldType === 'media' && typeof value === 'string' && (MEDIA_PATH.test(value) || MEDIA_EXT.test(value))) {
+        return { source: 'local', url: value, alt: '' };
+    }
+    if (fieldType === 'richtext' && typeof value === 'string') {
+        return toRichTextDoc(value);
+    }
+    return value;
+}
+function loadSourceRows(rootDir, source) {
+    const filePath = join(rootDir, source);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = /\.ya?ml$/.test(source) ? YAML.parse(raw) : JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stage rows for every draft. Drafts carry the inferred field types, the
+ * scan carries the raw rows (typedRows for in-code candidates; data files
+ * are re-read from disk for the full, untruncated dataset).
+ */
+export function writeRowsStaging(rootDir, scan, drafts) {
+    const rowsDir = join(rootDir, '.fimo', 'migration', 'rows');
+    rmSync(rowsDir, { recursive: true, force: true });
+    if (drafts.length === 0) {
+        return 0;
+    }
+    const bySourceLabel = new Map(drafts.map((draft) => [draft.source, draft]));
+    const provisionalByName = new Map(drafts.map((draft) => [draft.sourceName, draft.uid]));
+    const toProvisional = (name) => provisionalByName.get(name) ?? name;
+    let written = 0;
+    const stage = (draft, source, rawRows, references) => {
+        const fieldTypes = new Map(Object.entries(draft.fields).map(([name, def]) => [
+            name,
+            def && typeof def === 'object' ? (def.type ?? 'string') : 'string',
+        ]));
+        const referenceFields = new Set(references.map((reference) => reference.field));
+        const rows = rawRows.map((row) => {
+            const out = {};
+            for (const [key, value] of Object.entries(row)) {
+                // Reference values stay as SOURCE values for later resolution.
+                out[key] = referenceFields.has(key) ? value : transformValue(fieldTypes.get(key), value);
+            }
+            return out;
+        });
+        const descriptor = {};
+        for (const reference of references) {
+            const targets = reference.targets.map(toProvisional);
+            descriptor[reference.field] = {
+                ...(targets.length > 1 ? { targets } : { target: targets[0] }),
+                by: 'slug',
+                ...(reference.many ? { many: true } : {}),
+            };
+        }
+        mkdirSync(rowsDir, { recursive: true });
+        writeFileSync(join(rowsDir, `${draft.uid}.rows.json`), `${JSON.stringify({ draftUid: draft.uid, source, references: descriptor, rows }, null, 1)}\n`);
+        written += 1;
+    };
+    for (const candidate of scan.collections) {
+        const label = `${candidate.file}:${candidate.line}`;
+        const draft = bySourceLabel.get(label);
+        if (!draft || !candidate.typedRows || candidate.typedRows.length === 0) {
+            continue;
+        }
+        stage(draft, label, candidate.typedRows, (candidate.references ?? []).map((reference) => ({
+            field: reference.field,
+            targets: reference.targets,
+            many: reference.many,
+        })));
+    }
+    for (const dataFile of scan.dataFiles) {
+        const draft = bySourceLabel.get(dataFile.file);
+        if (!draft) {
+            continue;
+        }
+        // Markdown groups can't be re-read from a single path (`<dir>/*.md`) — the
+        // scanner already parsed every document into the collection's typedRows.
+        const rawRows = dataFile.kind === 'markdown'
+            ? (dataFile.collections[0]?.typedRows ?? null)
+            : loadSourceRows(rootDir, dataFile.file);
+        if (!rawRows) {
+            continue;
+        }
+        const references = dataFile.collections.flatMap((collection) => (collection.references ?? []).map((reference) => ({
+            field: reference.field,
+            targets: reference.targets,
+            many: reference.many,
+        })));
+        stage(draft, dataFile.file, rawRows, references);
+    }
+    return written;
+}

package/dist/scripts/draft-rows.test.d.ts

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