fimo 0.8.0 → 0.9.0-experimental.10

package/dist/scripts/frameworks/astro/routes.js

@@ -0,0 +1,44 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pushRoute, toSegment } from '../discovered-route.js';
+const PAGE_EXT = /\.(astro|md|mdx|html)$/;
+/** Astro file-based routes under src/pages (index files map to the dir path). */
+export function discoverAstroRoutes(pagesDir) {
+    const routes = [];
+    const walk = (dir, segments) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            // Astro's convention: underscore-prefixed files AND directories are
+            // excluded from routing (component folders inside src/pages).
+            if (entry.startsWith('_')) {
+                continue;
+            }
+            if (isDir) {
+                walk(full, [...segments, toSegment(entry)]);
+                continue;
+            }
+            if (!PAGE_EXT.test(entry)) {
+                continue;
+            }
+            const base = entry.replace(PAGE_EXT, '');
+            pushRoute(routes, base === 'index' ? segments : [...segments, toSegment(base)], full);
+        }
+    };
+    walk(pagesDir, []);
+    routes.sort((a, b) => a.path.localeCompare(b.path));
+    return routes;
+}

package/dist/scripts/frameworks/astro/template-style.d.ts

@@ -0,0 +1,7 @@
+import type { TemplateWrapStyle } from '../../apply-wrap-templates.js';
+/**
+ * Astro template wraps: t() resolves in the frontmatter (server-only, so the
+ * server barrel is safe to import there), values interpolate as {t(...)}.
+ * Files without a frontmatter fence get one — Astro allows an empty fence.
+ */
+export declare const astroTemplateWrapStyle: TemplateWrapStyle;

package/dist/scripts/frameworks/astro/template-style.js

@@ -0,0 +1,19 @@
+/**
+ * Astro template wraps: t() resolves in the frontmatter (server-only, so the
+ * server barrel is safe to import there), values interpolate as {t(...)}.
+ * Files without a frontmatter fence get one — Astro allows an empty fence.
+ */
+export const astroTemplateWrapStyle = {
+    ext: '.astro',
+    head: 'import { loadFimoT } from "fimo/astro/server";\nconst t = await loadFimoT();',
+    headMarker: /loadFimoT/,
+    open: '{t(',
+    close: ')}',
+    injectHead: (code, head) => {
+        const fence = code.match(/^---\r?\n/);
+        if (fence) {
+            return `${code.slice(0, fence[0].length)}${head}\n${code.slice(fence[0].length)}`;
+        }
+        return `---\n${head}\n---\n${code}`;
+    },
+};

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

@@ -0,0 +1,83 @@
+import type { TemplateWrapStyle } from '../apply-wrap-templates.js';
+import type { FrameworkDetection } from '../detect-framework.js';
+import { type RouteFileResolution, type RouteLike } from '../routes/module-resolve.js';
+import { type CollectionRewireResult } from './next/rewire.js';
+import { type DiscoveredRoute } from './next/routes.js';
+import { type RootWiringResult } from './next/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 declare function discoverFrameworkRoutes(cwd: string, detection: FrameworkDetection): DiscoveredRoute[];
+/**
+ * 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 declare function frameworkDataDirs(framework: string | null | undefined): string[];
+/**
+ * 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 declare function frameworkJsxWrapperModule(detection: Pick<FrameworkDetection, 'framework' | 'react'>): string | 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 declare function frameworkTemplateWrapStyle(framework: string | null | undefined): TemplateWrapStyle | null;
+export declare function frameworkRouteFiles(framework: string | null): ((cwd: string, routes: Record<string, RouteLike>) => RouteFileResolution[]) | null;
+export interface SectionStyle {
+    /** Module extensions a section import may resolve to. */
+    extensions: string[];
+    /** Wrapped-key scope for a component file (must match the wrap codemod's
+     *  own scoping so drafted sections join their staged keys). */
+    fileScope: (relFile: string) => string;
+    /** Directories tried for auto-imported components (Nuxt convention) when
+     *  a section tag has no import statement. */
+    fallbackComponentDirs: string[];
+}
+/**
+ * How to read a page's SECTION STRUCTURE for this framework — the seam the
+ * page-structure drafter builds on. Template frameworks share the ES-import
+ * + capitalized-tag shape, differing only in extensions and key scoping.
+ */
+export declare function frameworkSectionStyle(framework: string | null): SectionStyle;
+/** Client-rendered frameworks: no server pass — reads happen in the browser
+ *  (the prompt's collection recipe and the SPA providers key off this). */
+export declare function isClientRenderedFramework(framework: string | null | undefined): boolean;
+export declare function frameworkRootWiring(detection: Pick<FrameworkDetection, 'framework' | 'react' | 'appDir'>): ((cwd: string) => RootWiringResult) | 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 declare function frameworkCollectionRewire(detection: Pick<FrameworkDetection, 'framework' | 'appDir'>): ((cwd: string, scan: unknown, drafts: Array<{
+    uid: string;
+    sourceName: string;
+    source: string;
+}>) => CollectionRewireResult) | null;
+export interface WiringMarker {
+    /** Candidate files, relative to the project root; ONE must contain the marker. */
+    files: string[];
+    marker: RegExp;
+    /** Human hint rendered when the marker is missing. */
+    hint: string;
+    /** Missing marker warns instead of failing (no automated recipe yet). */
+    warnOnly?: boolean;
+}
+/**
+ * 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 declare function frameworkWiringMarker(detection: Pick<FrameworkDetection, 'framework' | 'react' | 'appDir'>, cwd?: string): WiringMarker | null;

package/dist/scripts/frameworks/discover.js

@@ -0,0 +1,288 @@
+import { existsSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { keyScope, slugify } from '../apply-wrap.js';
+import { DEFAULT_COMPONENT_EXTENSIONS } from '../routes/module-resolve.js';
+import { discoverAstroRoutes } from './astro/routes.js';
+import { astroTemplateWrapStyle } from './astro/template-style.js';
+import { rewireNextCollectionPages } from './next/rewire.js';
+import { discoverNextPagesRoutes, discoverNextRoutes, resolveNextRouteFiles, } from './next/routes.js';
+import { ensureNextLayoutWiring, nextRootLayoutFiles } 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, resolveSpaRouteFiles } 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);
+    }
+    // Library-mode React Router (react-router dep on Vite, no app/ convention)
+    // declares routes in code exactly like a vite+react SPA — the Fimo-site
+    // dogfood detected `react-router` and fell to `default: []`, forcing 22
+    // manual `pages set` calls while the SPA scanner would have found them all.
+    if (detection.framework === 'react-router' && !detection.pagesDir) {
+        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 'react-router':
+            // Library-mode React Router SPAs (react-router dep on Vite) wrap with
+            // the client-side fimo/react primitives — same shape as vite+react.
+            // Proven on the Fimo marketing site (1211 items auto-wrapped).
+            return 'fimo/react';
+        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.
+ */
+/**
+ * Registry route ids → the component files that render them — the join the
+ * label-ownership prefill and the page-structure drafter build on. Framework
+ * knowledge stays HERE: core modules call this and never test a framework
+ * name themselves. File-based frameworks resolve straight from their
+ * discovery output (the walk knows every route's file); code-declared
+ * routers (SPA) resolve through import analysis.
+ */
+function resolveByDiscovery(discover, conventionalDirs) {
+    return (cwd, routes) => {
+        const pagesDir = conventionalDirs.map((dir) => join(cwd, dir)).find((dir) => existsSync(dir));
+        if (!pagesDir) {
+            return [];
+        }
+        const byPath = new Map();
+        for (const [routeId, route] of Object.entries(routes)) {
+            if (typeof route?.path === 'string') {
+                byPath.set(route.path, routeId);
+            }
+        }
+        const resolutions = [];
+        for (const discovered of discover(pagesDir)) {
+            const routeId = byPath.get(discovered.path);
+            if (routeId && discovered.file) {
+                resolutions.push({ routeId, file: discovered.file });
+            }
+        }
+        return resolutions;
+    };
+}
+export function frameworkRouteFiles(framework) {
+    switch (framework) {
+        case 'next':
+            return resolveNextRouteFiles;
+        case 'react-router':
+        case 'vite':
+            return resolveSpaRouteFiles;
+        case 'astro':
+            return resolveByDiscovery(discoverAstroRoutes, ['src/pages', 'pages']);
+        case 'nuxt':
+            return resolveByDiscovery(discoverNuxtRoutes, ['pages', 'src/pages']);
+        case 'sveltekit':
+            return resolveByDiscovery(discoverSvelteKitRoutes, ['src/routes']);
+        case 'remix':
+            return resolveByDiscovery(discoverRemixRoutes, ['app/routes']);
+        default:
+            return null;
+    }
+}
+/**
+ * How to read a page's SECTION STRUCTURE for this framework — the seam the
+ * page-structure drafter builds on. Template frameworks share the ES-import
+ * + capitalized-tag shape, differing only in extensions and key scoping.
+ */
+export function frameworkSectionStyle(framework) {
+    const templateScope = (relFile) => {
+        const style = frameworkTemplateWrapStyle(framework);
+        return style?.fileScope?.(relFile) ?? slugify(basename(relFile).replace(/\.[a-z0-9]+$/i, '')) ?? 'shared';
+    };
+    switch (framework) {
+        case 'astro':
+            return {
+                extensions: ['.astro', '.tsx', '.jsx', '.ts', '.js'],
+                fileScope: templateScope,
+                fallbackComponentDirs: [],
+            };
+        case 'nuxt':
+            return {
+                extensions: ['.vue', '.ts', '.js'],
+                fileScope: templateScope,
+                fallbackComponentDirs: ['components'],
+            };
+        case 'sveltekit':
+            return { extensions: ['.svelte', '.ts', '.js'], fileScope: templateScope, fallbackComponentDirs: [] };
+        default:
+            return { extensions: DEFAULT_COMPONENT_EXTENSIONS.slice(), fileScope: keyScope, fallbackComponentDirs: [] };
+    }
+}
+/** Client-rendered frameworks: no server pass — reads happen in the browser
+ *  (the prompt's collection recipe and the SPA providers key off this). */
+export function isClientRenderedFramework(framework) {
+    return framework === 'vite' || framework === 'react-router';
+}
+export function frameworkRootWiring(detection) {
+    switch (detection.framework) {
+        case 'next':
+            return (cwd) => ensureNextLayoutWiring(cwd, detection);
+        case 'react-router':
+            // Same createRoot(...).render entry shape as vite+react; framework-mode
+            // RR apps have no src/main.* and bail with a reason (agent §0).
+            return ensureSpaEntryWiring;
+        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, cwd) {
+    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,
+                };
+            }
+            // Resolve the real root layout(s), including the next-intl `[locale]`
+            // segment; fall back to the direct path when nothing is on disk yet.
+            const resolved = cwd ? nextRootLayoutFiles(cwd, detection.appDir).map((file) => relative(cwd, file)) : [];
+            const files = resolved.length > 0
+                ? resolved
+                : [`${detection.appDir}/layout.tsx`, `${detection.appDir}/layout.jsx`, `${detection.appDir}/layout.js`];
+            return {
+                files,
+                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 'react-router':
+            // Accept either provider: FimoSpaProviders (the vite+react codemod) or
+            // FimoProviders (the fimo/react-router adapter, hand-wired on RR sites).
+            return {
+                files: ['src/main.tsx', 'src/main.jsx', 'src/index.tsx', 'src/index.jsx', 'app/root.tsx', 'app/root.jsx'],
+                marker: /Fimo(Spa)?Providers/,
+                hint: 'wrap the root render with FimoSpaProviders (fimo/react) or FimoProviders (fimo/react-router) — 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/discovered-route.d.ts

@@ -0,0 +1,9 @@
+import type { DiscoveredRoute } from './next/routes.js';
+/**
+ * Shared helpers for file-based route discovery — one implementation of the
+ * segment→route push and the bracket-param normalization that astro, nuxt,
+ * sveltekit, and remix previously each carried a copy of.
+ */
+export declare function pushRoute(routes: DiscoveredRoute[], parts: string[], file?: string): void;
+/** `[slug]` → `:slug`, `[...rest]` → `:rest` (bracket file conventions). */
+export declare const toSegment: (name: string) => string;

package/dist/scripts/frameworks/discovered-route.js

@@ -0,0 +1,17 @@
+import { discoveredRouteLabel } from '../lib/humanize.js';
+/**
+ * Shared helpers for file-based route discovery — one implementation of the
+ * segment→route push and the bracket-param normalization that astro, nuxt,
+ * sveltekit, and remix previously each carried a copy of.
+ */
+export function pushRoute(routes, parts, file) {
+    const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
+    routes.push({
+        id: routePath === '/' ? 'home' : parts.map((part) => part.replace(/^:/, '')).join('-'),
+        path: routePath,
+        label: discoveredRouteLabel(routePath),
+        ...(file ? { file } : {}),
+    });
+}
+/** `[slug]` → `:slug`, `[...rest]` → `:rest` (bracket file conventions). */
+export const toSegment = (name) => name.replace(/^\[\.\.\.(.+)\]$/, ':$1').replace(/^\[(.+)\]$/, ':$1');

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

@@ -0,0 +1,43 @@
+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 RewiredPage {
+    file: string;
+    /** Collection uid the page reads through `wrapCollection` (provisional until
+     *  `adopt-drafts` renames it). */
+    uid: string;
+    /** The page's registry route path (`:param` normalized), null when the file
+     *  sits in a non-routable location. Joins the page back to the page registry
+     *  as binding evidence. */
+    routePath: string | null;
+}
+export interface CollectionRewireResult {
+    changes: string[];
+    warnings: string[];
+    /** Pages successfully rewired. */
+    rewired: number;
+    /** Every page known to read a collection through `wrapCollection` — rewired
+     *  this run or found already wired on a re-run. */
+    pages: RewiredPage[];
+}
+export declare function rewireNextCollectionPages(cwd: string, detection: Pick<FrameworkDetection, 'appDir'>, scan: WrapScanResult, drafts: Array<{
+    uid: string;
+    sourceName: string;
+    source: string;
+}>): CollectionRewireResult;