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

package/dist/scripts/frameworks/discover.js

@@ -0,0 +1,171 @@
+import { join } from 'node:path';
+import { discoverAstroRoutes } from './astro/routes.js';
+import { astroTemplateWrapStyle } from './astro/template-style.js';
+import { rewireNextCollectionPages } from './next/rewire.js';
+import { discoverNextPagesRoutes, discoverNextRoutes } from './next/routes.js';
+import { ensureNextLayoutWiring } from './next/wiring.js';
+import { discoverNuxtRoutes } from './nuxt/routes.js';
+import { nuxtTemplateWrapStyle } from './nuxt/template-style.js';
+import { discoverRemixRoutes } from './remix/routes.js';
+import { discoverSvelteKitRoutes } from './sveltekit/routes.js';
+import { svelteTemplateWrapStyle } from './sveltekit/template-style.js';
+import { discoverReactRouterDomRoutes } from './vite/routes.js';
+import { ensureSpaEntryWiring } from './vite/wiring.js';
+/**
+ * Route discovery for any detected framework — the single registry generic
+ * code calls. Frameworks without a file convention (vue SPA, plain vite)
+ * return [] and rely on fimo-config routes.
+ */
+export function discoverFrameworkRoutes(cwd, detection) {
+    if (detection.framework === 'vite' && detection.react) {
+        return discoverReactRouterDomRoutes(cwd);
+    }
+    switch (detection.framework) {
+        case 'next':
+            return [
+                ...(detection.appDir ? discoverNextRoutes(join(cwd, detection.appDir)) : []),
+                ...(detection.pagesDir ? discoverNextPagesRoutes(join(cwd, detection.pagesDir)) : []),
+            ];
+        case 'remix':
+            return detection.pagesDir ? discoverRemixRoutes(join(cwd, detection.pagesDir)) : [];
+        case 'astro':
+            return detection.pagesDir ? discoverAstroRoutes(join(cwd, detection.pagesDir)) : [];
+        case 'nuxt':
+            return detection.pagesDir ? discoverNuxtRoutes(join(cwd, detection.pagesDir)) : [];
+        case 'sveltekit':
+            return detection.pagesDir ? discoverSvelteKitRoutes(join(cwd, detection.pagesDir)) : [];
+        default:
+            return [];
+    }
+}
+/**
+ * Extra directories the framework keeps page COPY in, outside any source
+ * root (data-file scanning). Part of the framework registry so generic
+ * scanners never carry framework names.
+ */
+export function frameworkDataDirs(framework) {
+    switch (framework) {
+        case 'nuxt':
+            return ['content']; // Nuxt Content convention (.yml/.md page documents)
+        default:
+            return [];
+    }
+}
+/**
+ * The wrapper-import module for frameworks whose .jsx/.tsx is guaranteed
+ * React — the only ones the --apply JSX codemod may touch. Template
+ * frameworks return null: a .tsx island there may be Solid or Preact, and
+ * injecting a React wrapper import breaks the build (bento dogfood). Bare
+ * Vite qualifies only with the detection's `react` flag (a react dependency
+ * pins the JSX runtime); the SPA primitives live in fimo/react and are
+ * fallback-safe before the providers are wired.
+ */
+export function frameworkJsxWrapperModule(detection) {
+    switch (detection.framework) {
+        case 'next':
+            return 'fimo/next';
+        case 'remix':
+            return 'fimo/remix';
+        case 'vite':
+            return detection.react ? 'fimo/react' : null;
+        default:
+            return null;
+    }
+}
+/**
+ * The template-wrap style for frameworks whose template files the --apply
+ * codemod may touch (plain text nodes only). Vue SPA stays null: without a
+ * server data path there is no deterministic t() wiring to inject.
+ */
+export function frameworkTemplateWrapStyle(framework) {
+    switch (framework) {
+        case 'astro':
+            return astroTemplateWrapStyle;
+        case 'nuxt':
+            return nuxtTemplateWrapStyle;
+        case 'sveltekit':
+            return svelteTemplateWrapStyle;
+        default:
+            return null;
+    }
+}
+/**
+ * The one-time root-wiring codemod for frameworks whose providers mount in a
+ * single well-known file (Next.js app router: the root layout; Vite React
+ * SPA: the entry). Runs during --apply, AFTER the baseline capture — the
+ * pre-wrap dev-server boot must not require the fimo package, and providers
+ * are render-transparent so the parity check stays clean. Template
+ * frameworks wire through their TemplateWrapStyle.ensureWiring hooks instead.
+ */
+export function frameworkRootWiring(detection) {
+    switch (detection.framework) {
+        case 'next':
+            return (cwd) => ensureNextLayoutWiring(cwd, detection);
+        case 'vite':
+            return detection.react ? ensureSpaEntryWiring : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Collection-page rewiring: pages that render a machine-staged collection get
+ * their data source switched to `wrapCollection` (Fimo overlay over the
+ * retained source rows) mechanically, with per-page bail reasons. Runs during
+ * --apply after drafts are staged; adopt-drafts renames the call-site uids.
+ * Next.js app router only for now.
+ */
+export function frameworkCollectionRewire(detection) {
+    switch (detection.framework) {
+        case 'next':
+            return (cwd, scan, drafts) => rewireNextCollectionPages(cwd, detection, scan, drafts);
+        default:
+            return null;
+    }
+}
+/**
+ * How `wrap --check` proves the root wiring exists: without providers the
+ * wrapped values render fallbacks forever, and neither coverage (counts
+ * wraps), parity (fallbacks render identically), nor seeding (DB-side)
+ * notices — editability would ship silently broken.
+ */
+export function frameworkWiringMarker(detection) {
+    switch (detection.framework) {
+        case 'next':
+            if (!detection.appDir) {
+                return {
+                    files: ['pages/_app.tsx', 'pages/_app.jsx', 'src/pages/_app.tsx', 'src/pages/_app.jsx'],
+                    marker: /FimoNextProviders/,
+                    hint: 'mount FimoNextProviders in pages/_app (pages router has no automated recipe yet)',
+                    warnOnly: true,
+                };
+            }
+            return {
+                files: [`${detection.appDir}/layout.tsx`, `${detection.appDir}/layout.jsx`, `${detection.appDir}/layout.js`],
+                marker: /FimoNextProviders/,
+                hint: `mount FimoNextProviders + FimoNextScripts in ${detection.appDir}/layout (agent prompt section 0)`,
+            };
+        case 'vite':
+            if (!detection.react) {
+                return null;
+            }
+            return {
+                files: ['src/main.tsx', 'src/main.jsx', 'src/index.tsx', 'src/index.jsx'],
+                marker: /FimoSpaProviders/,
+                hint: 'wrap the root render with FimoSpaProviders from fimo/react (agent prompt section 0)',
+            };
+        case 'remix':
+            return {
+                files: ['app/root.tsx', 'app/root.jsx'],
+                marker: /FimoRemixProviders/,
+                hint: 'mount FimoRemixProviders in app/root (agent prompt section 0)',
+            };
+        case 'sveltekit':
+            return {
+                files: ['src/routes/+layout.server.js', 'src/routes/+layout.server.ts'],
+                marker: /fimoLabels/,
+                hint: 'return fimoLabels from the root +layout.server load (wrap.md SvelteKit notes)',
+            };
+        default:
+            return null;
+    }
+}

package/dist/scripts/frameworks/next/rewire.d.ts

@@ -0,0 +1,30 @@
+import type { FrameworkDetection } from '../../detect-framework.js';
+import type { WrapScanResult } from '../../scan-wrappable.js';
+/**
+ * Page rewiring for wrap-migrated collections: make each page that renders a
+ * machine-staged collection read from Fimo through `wrapCollection` while
+ * KEEPING its source rows as the render fallback. Two safe shapes:
+ *
+ * - an in-code array literal (`const clients = [...]`) rendered by the
+ *   page's default-export function → the literal is extracted byte-faithful
+ *   to `src/data/<name>.json` (it becomes the fallback file) and the
+ *   component fetches `wrapCollection('<Uid>', clientsSource)`;
+ * - a data-file default import (`import posts from '../src/data/posts.json'`)
+ *   → the import becomes `postsSource` and the component fetches
+ *   `wrapCollection('<Uid>', postsSource)`.
+ *
+ * Everything else bails with a reason that flows into the agent prompt.
+ * Uids are the PROVISIONAL draft names; `schemas adopt-drafts` rewrites the
+ * call sites through its renames.
+ */
+export interface CollectionRewireResult {
+    changes: string[];
+    warnings: string[];
+    /** Pages successfully rewired. */
+    rewired: number;
+}
+export declare function rewireNextCollectionPages(cwd: string, detection: Pick<FrameworkDetection, 'appDir'>, scan: WrapScanResult, drafts: Array<{
+    uid: string;
+    sourceName: string;
+    source: string;
+}>): CollectionRewireResult;

package/dist/scripts/frameworks/next/rewire.js

@@ -0,0 +1,258 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { ensureFimoImport } from '../../apply-wrap.js';
+function applyEdits(code, edits) {
+    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);
+    }
+    return next;
+}
+function walkAll(node, visit) {
+    if (!node || typeof node !== 'object') {
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const child of node) {
+            walkAll(child, visit);
+        }
+        return;
+    }
+    const record = node;
+    if (typeof record.type === 'string') {
+        visit(record);
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (key !== 'type' && value && typeof value === 'object') {
+            walkAll(value, visit);
+        }
+    }
+}
+function defaultExportFunction(program) {
+    const exportDefault = (program.body ?? []).find((node) => node.type === 'ExportDefaultDeclaration');
+    if (!exportDefault || exportDefault.declaration?.type !== 'FunctionDeclaration') {
+        return null;
+    }
+    const body = exportDefault.declaration.body;
+    if (!body || (body.type !== 'FunctionBody' && body.type !== 'BlockStatement')) {
+        return null;
+    }
+    return exportDefault.declaration;
+}
+/** Every reference to `name` (outside `ignoredSpans`) must sit inside the
+ *  component body — otherwise moving the binding into the component would
+ *  break module-level consumers (metadata, generateStaticParams, …). */
+function referencesConfinedToFunction(program, name, fn, ignoredSpans) {
+    let confined = true;
+    walkAll(program, (node) => {
+        if (node.type !== 'Identifier' || node.name !== name) {
+            return;
+        }
+        const inIgnored = ignoredSpans.some((span) => node.start >= span.start && node.end <= span.end);
+        const inFn = node.start >= fn.body.start && node.end <= fn.body.end;
+        if (!inIgnored && !inFn) {
+            confined = false;
+        }
+    });
+    return confined;
+}
+function relativeImport(fromFile, toFile) {
+    const rel = path.relative(path.dirname(fromFile), toFile).split(path.sep).join('/');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+function pageFilesUnder(dir) {
+    const out = [];
+    const walk = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+                continue;
+            }
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (/\.(tsx|jsx|js)$/.test(entry.name)) {
+                out.push(full);
+            }
+        }
+    };
+    if (fs.existsSync(dir)) {
+        walk(dir);
+    }
+    return out;
+}
+export function rewireNextCollectionPages(cwd, detection, scan, drafts) {
+    const changes = [];
+    const warnings = [];
+    let rewired = 0;
+    if (!detection.appDir) {
+        return { changes, warnings: ['Collection pages not rewired: pages-router project.'], rewired };
+    }
+    const appDirAbs = path.join(cwd, detection.appDir);
+    const uidBySourceName = new Map(drafts.map((draft) => [draft.sourceName, draft.uid]));
+    const draftsBySourceFile = new Map();
+    for (const draft of drafts) {
+        const bucket = draftsBySourceFile.get(draft.source) ?? [];
+        bucket.push(draft.uid);
+        draftsBySourceFile.set(draft.source, bucket);
+    }
+    const bail = (page, reason) => {
+        warnings.push(`Page not rewired (${page}): ${reason} — wire it with wrapCollection per the prompt recipe.`);
+    };
+    // ── In-code array literals: extract to src/data/<name>.json + wire ──
+    for (const candidate of scan.collections) {
+        const pageAbs = path.join(cwd, candidate.file);
+        if (!pageAbs.startsWith(appDirAbs + path.sep)) {
+            bail(candidate.file, `in-code collection \`${candidate.name}\` sits outside the app directory`);
+            continue;
+        }
+        const uid = uidBySourceName.get(candidate.name);
+        if (!uid) {
+            continue;
+        }
+        const rows = candidate.typedRows;
+        if (!rows || rows.length !== candidate.count) {
+            bail(candidate.file, `\`${candidate.name}\` is larger than the extraction window`);
+            continue;
+        }
+        const code = fs.readFileSync(pageAbs, 'utf8');
+        if (code.includes("'use client'") || code.includes('"use client"')) {
+            bail(candidate.file, 'client component (no server fetch)');
+            continue;
+        }
+        let program;
+        try {
+            program = parseSync(pageAbs, code).program;
+        }
+        catch {
+            bail(candidate.file, 'could not parse');
+            continue;
+        }
+        // `const x = [...]`, `= [...] as const`, `= [...] satisfies T` all count.
+        const isArrayInit = (init) => {
+            const inner = init?.type === 'TSAsExpression' || init?.type === 'TSSatisfiesExpression' ? init.expression : init;
+            return inner?.type === 'ArrayExpression';
+        };
+        const declaration = (program.body ?? []).find((node) => node.type === 'VariableDeclaration' &&
+            node.declarations?.length === 1 &&
+            node.declarations[0]?.id?.name === candidate.name &&
+            isArrayInit(node.declarations[0]?.init));
+        if (!declaration) {
+            bail(candidate.file, `top-level \`const ${candidate.name} = [...]\` not found`);
+            continue;
+        }
+        const fn = defaultExportFunction(program);
+        if (!fn) {
+            bail(candidate.file, 'the default export is not a plain function declaration');
+            continue;
+        }
+        if (!referencesConfinedToFunction(program, candidate.name, fn, [declaration])) {
+            bail(candidate.file, `\`${candidate.name}\` is referenced outside the page component`);
+            continue;
+        }
+        const dataDir = path.join(cwd, 'src', 'data');
+        const dataFileAbs = path.join(dataDir, `${candidate.name}.json`);
+        if (fs.existsSync(dataFileAbs)) {
+            bail(candidate.file, `src/data/${candidate.name}.json already exists`);
+            continue;
+        }
+        fs.mkdirSync(dataDir, { recursive: true });
+        fs.writeFileSync(dataFileAbs, `${JSON.stringify(rows, null, 2)}\n`);
+        const edits = [{ start: declaration.start, end: declaration.end, replacement: '' }];
+        if (!fn.async) {
+            edits.push({ start: fn.start, end: fn.start, replacement: 'async ' });
+        }
+        edits.push({
+            start: fn.body.start + 1,
+            end: fn.body.start + 1,
+            replacement: `\n  const ${candidate.name} = await wrapCollection('${uid}', ${candidate.name}Source);\n`,
+        });
+        let next = applyEdits(code, edits);
+        next = `import ${candidate.name}Source from '${relativeImport(pageAbs, dataFileAbs)}';\n${next}`;
+        next = ensureFimoImport(next, ['wrapCollection'], 'fimo/next/server');
+        fs.writeFileSync(pageAbs, next);
+        rewired += 1;
+        changes.push(`rewired ${candidate.file}: \`${candidate.name}\` extracted to src/data/${candidate.name}.json and read through wrapCollection('${uid}')`);
+    }
+    // ── Data-file default imports: wire the importing pages ──
+    const dataFileUids = new Map();
+    for (const dataFile of scan.dataFiles) {
+        const uids = draftsBySourceFile.get(dataFile.file);
+        if (uids && uids.length === 1 && /\.json$/i.test(dataFile.file)) {
+            dataFileUids.set(path.resolve(cwd, dataFile.file), uids[0]);
+        }
+    }
+    if (dataFileUids.size > 0) {
+        for (const pageAbs of pageFilesUnder(appDirAbs)) {
+            const code = fs.readFileSync(pageAbs, 'utf8');
+            const rel = path.relative(cwd, pageAbs);
+            if (!code.includes('src/data/')) {
+                continue;
+            }
+            if (code.includes('wrapCollection(')) {
+                continue;
+            }
+            let program;
+            try {
+                program = parseSync(pageAbs, code).program;
+            }
+            catch {
+                continue;
+            }
+            const imports = (program.body ?? []).filter((node) => node.type === 'ImportDeclaration' && typeof node.source?.value === 'string');
+            const targets = [];
+            for (const declaration of imports) {
+                const specifier = (declaration.specifiers ?? []).find((entry) => entry.type === 'ImportDefaultSpecifier');
+                if (!specifier || !declaration.source.value.startsWith('.')) {
+                    continue;
+                }
+                const resolved = path.resolve(path.dirname(pageAbs), declaration.source.value);
+                const uid = dataFileUids.get(resolved);
+                if (uid) {
+                    targets.push({ node: declaration, local: specifier.local.name, uid });
+                }
+            }
+            if (targets.length === 0) {
+                continue;
+            }
+            if (code.includes("'use client'") || code.includes('"use client"')) {
+                bail(rel, 'client component (no server fetch)');
+                continue;
+            }
+            const fn = defaultExportFunction(program);
+            if (!fn) {
+                bail(rel, 'the default export is not a plain function declaration');
+                continue;
+            }
+            const confined = targets.every((target) => referencesConfinedToFunction(program, target.local, fn, [target.node]));
+            if (!confined) {
+                bail(rel, 'the imported collection is referenced outside the page component');
+                continue;
+            }
+            const edits = [];
+            if (!fn.async) {
+                edits.push({ start: fn.start, end: fn.start, replacement: 'async ' });
+            }
+            for (const target of targets) {
+                const specifier = (target.node.specifiers ?? []).find((entry) => entry.type === 'ImportDefaultSpecifier');
+                edits.push({
+                    start: specifier.local.start,
+                    end: specifier.local.end,
+                    replacement: `${target.local}Source`,
+                });
+                edits.push({
+                    start: fn.body.start + 1,
+                    end: fn.body.start + 1,
+                    replacement: `\n  const ${target.local} = await wrapCollection('${target.uid}', ${target.local}Source);\n`,
+                });
+            }
+            let next = applyEdits(code, edits);
+            next = ensureFimoImport(next, ['wrapCollection'], 'fimo/next/server');
+            fs.writeFileSync(pageAbs, next);
+            rewired += 1;
+            changes.push(`rewired ${rel}: ${targets.map((target) => `wrapCollection('${target.uid}')`).join(', ')} over the imported source rows`);
+        }
+    }
+    return { changes, warnings, rewired };
+}

package/dist/scripts/frameworks/next/rewire.test.d.ts

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

package/dist/scripts/frameworks/next/rewire.test.js

@@ -0,0 +1,134 @@
+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 { writeSchemaDrafts } from '../../draft-schemas.js';
+import { scanWrappable } from '../../scan-wrappable.js';
+import { rewireNextCollectionPages } from './rewire.js';
+let dir;
+const project = (files) => {
+    dir = mkdtempSync(join(tmpdir(), 'next-rewire-'));
+    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 });
+    }
+});
+const run = (root) => {
+    const scan = scanWrappable(root, { keepInternal: true });
+    const drafts = writeSchemaDrafts(root, scan);
+    return rewireNextCollectionPages(root, { appDir: 'app' }, scan, drafts);
+};
+const DATA_PAGE = `import posts from '../../src/data/posts.json';
+
+export default function PostsPage() {
+  return (
+    <main>
+      <h1>Posts</h1>
+      <ul>
+        {posts.slice(0, 24).map((item: any, idx: number) => (
+          <li key={idx}><span>{item.title}</span> <span>{item.excerpt}</span></li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+`;
+const POSTS_JSON = JSON.stringify([
+    { slug: 'post-1', title: 'Charting the bay', excerpt: 'First excerpt of the harbor.' },
+    { slug: 'post-2', title: 'Berth songs', excerpt: 'Second excerpt of the crew.' },
+    { slug: 'post-3', title: 'Lantern census', excerpt: 'Third excerpt of the reef.' },
+]);
+const INCODE_PAGE = `const clients = [
+  { "name": "Quay anchor Co", "slug": "client-0", "since": "2018-03-20" },
+  { "name": "Gull harbor Co", "slug": "client-1", "since": "2015-08-17" },
+  { "name": "Crane skiff Co", "slug": "client-2", "since": "2017-07-07" }
+];
+
+export default function ClientsPage() {
+  return (
+    <main>
+      <h1>Clients</h1>
+      <ul>
+        {clients.map((item, idx) => (
+          <li key={idx}><span>{item.name}</span> <span>{item.since}</span></li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+`;
+describe('rewireNextCollectionPages', () => {
+    it('wires a data-file import page through wrapCollection', () => {
+        const root = project({
+            'src/data/posts.json': POSTS_JSON,
+            'app/posts/page.tsx': DATA_PAGE,
+        });
+        const result = run(root);
+        expect(result.rewired).toBe(1);
+        const page = readFileSync(join(root, 'app/posts/page.tsx'), 'utf8');
+        expect(page).toContain("import postsSource from '../../src/data/posts.json'");
+        expect(page).toContain('export default async function PostsPage()');
+        expect(page).toContain("const posts = await wrapCollection('Post', postsSource);");
+        expect(page).toContain('import { wrapCollection } from "fimo/next/server"');
+    });
+    it('extracts an in-code array to src/data and wires the page', () => {
+        const root = project({
+            'app/clients/page.tsx': INCODE_PAGE,
+        });
+        const result = run(root);
+        expect(result.rewired).toBe(1);
+        const extracted = JSON.parse(readFileSync(join(root, 'src/data/clients.json'), 'utf8'));
+        expect(extracted).toHaveLength(3);
+        expect(extracted[0]).toEqual({ name: 'Quay anchor Co', slug: 'client-0', since: '2018-03-20' });
+        const page = readFileSync(join(root, 'app/clients/page.tsx'), 'utf8');
+        expect(page).toContain("import clientsSource from '../../src/data/clients.json'");
+        expect(page).toContain('export default async function ClientsPage()');
+        expect(page).toContain("const clients = await wrapCollection('Client', clientsSource);");
+        expect(page).not.toContain('"Quay anchor Co"');
+    });
+    it('extracts an `as const` in-code array (the generator/create-next-app shape)', () => {
+        const root = project({
+            'app/clients/page.tsx': INCODE_PAGE.replace('\n];', '\n] as const;'),
+        });
+        const result = run(root);
+        expect(result.rewired).toBe(1);
+        const page = readFileSync(join(root, 'app/clients/page.tsx'), 'utf8');
+        expect(page).toContain("const clients = await wrapCollection('Client', clientsSource);");
+        expect(page).not.toContain('as const');
+    });
+    it('bails on client components with a reason', () => {
+        const root = project({
+            'src/data/posts.json': POSTS_JSON,
+            'app/posts/page.tsx': `'use client';\n${DATA_PAGE}`,
+        });
+        const result = run(root);
+        expect(result.rewired).toBe(0);
+        expect(result.warnings.some((warning) => warning.includes('client component'))).toBe(true);
+    });
+    it('bails when the collection is referenced outside the page component', () => {
+        const root = project({
+            'app/clients/page.tsx': `${INCODE_PAGE}\nexport const clientCount = clients.length;\n`,
+        });
+        const result = run(root);
+        expect(result.rewired).toBe(0);
+        expect(result.warnings.some((warning) => warning.includes('referenced outside'))).toBe(true);
+    });
+    it('is idempotent: an already-wired page is left untouched', () => {
+        const root = project({
+            'src/data/posts.json': POSTS_JSON,
+            'app/posts/page.tsx': DATA_PAGE,
+        });
+        run(root);
+        const once = readFileSync(join(root, 'app/posts/page.tsx'), 'utf8');
+        const again = run(root);
+        expect(readFileSync(join(root, 'app/posts/page.tsx'), 'utf8')).toBe(once);
+        expect(again.warnings.filter((warning) => warning.includes('app/posts'))).toHaveLength(0);
+    });
+});

package/dist/scripts/frameworks/next/routes.d.ts

@@ -0,0 +1,17 @@
+export interface DiscoveredRoute {
+    id: string;
+    path: string;
+    label: string;
+}
+/**
+ * Discover page routes of a Next.js app-router directory (`app/` or
+ * `src/app/`). Returns display routes for `fimo-config.json#routes` so the
+ * Studio page switcher can enumerate a wrapped site's pages.
+ */
+export declare function discoverNextRoutes(appDir: string): DiscoveredRoute[];
+/**
+ * Pages-router discovery (`pages/` or `src/pages/`): every module is a route
+ * except `_app`/`_document`/`_error` and `api/`. `[param]` segments map to
+ * `:param` (the parity capture skips dynamic routes, same as app router).
+ */
+export declare function discoverNextPagesRoutes(pagesDir: string): DiscoveredRoute[];