fimo 0.6.0 → 0.7.0-experimental.10

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

@@ -0,0 +1,62 @@
+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 { detectStrapiTouchpoints } from './touchpoints.js';
+let dir;
+function frontend(files) {
+    dir = mkdtempSync(join(tmpdir(), 'strapi-touchpoints-'));
+    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('detectStrapiTouchpoints', () => {
+    it('enumerates deps, call sites, and env for a still-wired frontend', () => {
+        const cwd = frontend({
+            'package.json': JSON.stringify({
+                dependencies: { '@strapi/client': '^1.0.0', next: '16.0.0' },
+                devDependencies: { '@repo/strapi-types': 'workspace:*' },
+            }),
+            'src/lib/strapi.ts': "import { strapi } from '@strapi/client';\nexport const client = strapi({ baseURL: process.env.STRAPI_URL });\n",
+            'src/app/page.tsx': "const data = await client.collection('api::article.article').find();\n",
+            '.env': 'STRAPI_URL=https://cms.example.com\nNEXT_PUBLIC_STRAPI_URL=https://cms.example.com\nOTHER=1\n',
+        });
+        const result = detectStrapiTouchpoints(cwd);
+        expect(result.dependencies.sort()).toEqual(['@repo/strapi-types', '@strapi/client']);
+        expect(result.envVars.sort()).toEqual(['NEXT_PUBLIC_STRAPI_URL', 'STRAPI_URL']);
+        expect(result.callSites.map((site) => site.reason).sort()).toEqual(['env-ref', 'strapi-sdk-import', 'uid-ref']);
+        expect(result.callSites.find((site) => site.reason === 'strapi-sdk-import')?.file).toBe('src/lib/strapi.ts');
+        expect(result.clean).toBe(false);
+    });
+    it('reads a rewired frontend as clean — a lib/strapi.ts calling Fimo is not a touchpoint', () => {
+        const cwd = frontend({
+            'package.json': JSON.stringify({ dependencies: { fimo: '0.7.0', next: '16.0.0' } }),
+            // Same filename, but now Fimo-backed: no Strapi references.
+            'src/lib/strapi.ts': "import { fimoStrapiFetch } from 'fimo/strapi';\nexport const client = fimoStrapiFetch;\n",
+            'src/app/page.tsx': "const data = await client('/articles');\n",
+        });
+        const result = detectStrapiTouchpoints(cwd);
+        expect(result.dependencies).toEqual([]);
+        expect(result.callSites).toEqual([]);
+        expect(result.clean).toBe(true);
+    });
+    it('flags a lingering STRAPI env reference in config even when deps are gone', () => {
+        const cwd = frontend({
+            'package.json': JSON.stringify({ dependencies: { next: '16.0.0' } }),
+            'next.config.mjs': 'export default { images: { domains: [process.env.STRAPI_MEDIA_URL] } };\n',
+        });
+        const result = detectStrapiTouchpoints(cwd);
+        expect(result.dependencies).toEqual([]);
+        expect(result.callSites).toHaveLength(1);
+        expect(result.callSites[0]).toMatchObject({ file: 'next.config.mjs', reason: 'env-ref' });
+        expect(result.clean).toBe(false);
+    });
+});

package/dist/scripts/cms/strapi/wire-client.d.ts

@@ -0,0 +1,15 @@
+import type { CmsCollectionSchema } from '../types.js';
+/**
+ * Machine-wire a Strapi frontend to read from Fimo: emit the `fimo-strapi`
+ * module in the CMS client dir, then swap every bare `fetch(...)` in that dir
+ * to `fimoStrapiFetch(...)`. Because every Strapi client funnels through one
+ * `fetch`, this makes the WHOLE site read scaffolded content from Fimo — no
+ * per-method or per-call-site knowledge, no agent step. Unscaffolded types fall
+ * through to the live CMS inside the shim.
+ */
+export interface StrapiWireResult {
+    changes: string[];
+    warnings: string[];
+    wired: boolean;
+}
+export declare function wireStrapiClient(cwd: string, clientDir: string, schemas: CmsCollectionSchema[]): StrapiWireResult;

package/dist/scripts/cms/strapi/wire-client.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { renderFimoStrapiModule } from './wiring.js';
+function walk(node, visit) {
+    if (!node || typeof node !== 'object') {
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const child of node) {
+            walk(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') {
+            walk(value, visit);
+        }
+    }
+}
+/** Callee spans of bare `fetch(...)` calls (not `x.fetch()` / `this.fetch()`). */
+function bareFetchCallees(filePath, code) {
+    let program;
+    try {
+        program = parseSync(filePath, code).program;
+    }
+    catch {
+        return [];
+    }
+    const spans = [];
+    walk(program, (n) => {
+        if (n.type === 'CallExpression' && n.callee?.type === 'Identifier' && n.callee.name === 'fetch') {
+            spans.push({ start: n.callee.start, end: n.callee.end });
+        }
+    });
+    return spans;
+}
+function applyReplacements(code, edits) {
+    let next = code;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+        next = next.slice(0, edit.start) + edit.text + next.slice(edit.end);
+    }
+    return next;
+}
+function relativeImport(fromFile, toFile) {
+    const rel = path
+        .relative(path.dirname(fromFile), toFile)
+        .replace(/\.tsx?$/, '')
+        .split(path.sep)
+        .join('/');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+function sourceFiles(dir) {
+    const out = [];
+    const walkDir = (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()) {
+                walkDir(full);
+            }
+            else if (/\.(tsx?|jsx?|mjs)$/.test(entry.name)) {
+                out.push(full);
+            }
+        }
+    };
+    if (fs.existsSync(dir)) {
+        walkDir(dir);
+    }
+    return out;
+}
+export function wireStrapiClient(cwd, clientDir, schemas) {
+    const changes = [];
+    const warnings = [];
+    if (!fs.existsSync(clientDir)) {
+        return { changes, warnings: [`CMS client directory not found: ${path.relative(cwd, clientDir)}`], wired: false };
+    }
+    const modulePath = path.join(clientDir, 'fimo-strapi.ts');
+    fs.writeFileSync(modulePath, renderFimoStrapiModule(schemas));
+    changes.push(`generated ${path.relative(cwd, modulePath)}`);
+    let swapped = 0;
+    for (const file of sourceFiles(clientDir)) {
+        if (path.resolve(file) === path.resolve(modulePath)) {
+            continue;
+        }
+        const code = fs.readFileSync(file, 'utf8');
+        const spans = bareFetchCallees(file, code);
+        if (spans.length === 0) {
+            continue;
+        }
+        let next = applyReplacements(code, spans.map((span) => ({ ...span, text: 'fimoStrapiFetch' })));
+        next = `import { fimoStrapiFetch } from '${relativeImport(file, modulePath)}';\n${next}`;
+        fs.writeFileSync(file, next);
+        swapped += spans.length;
+        changes.push(`rewired ${path.relative(cwd, file)}: ${spans.length} fetch call(s) → fimoStrapiFetch`);
+    }
+    if (swapped === 0) {
+        warnings.push(`No bare fetch() call found under ${path.relative(cwd, clientDir)} — wire fimoStrapiFetch into the client manually.`);
+    }
+    return { changes, warnings, wired: swapped > 0 };
+}

package/dist/scripts/cms/strapi/wire-client.test.d.ts

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

package/dist/scripts/cms/strapi/wire-client.test.js

@@ -0,0 +1,51 @@
+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 { wireStrapiClient } from './wire-client.js';
+let dir;
+const schemas = [
+    {
+        name: 'BlogPost',
+        label: 'Blog Post',
+        isSingleton: false,
+        localized: false,
+        fields: {},
+        sourceUid: 'api::blog-post.blog-post',
+        sourcePath: '/blog-posts',
+    },
+];
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('wireStrapiClient', () => {
+    it('generates the fimo-strapi module and swaps bare fetch calls', () => {
+        dir = mkdtempSync(join(tmpdir(), 'wire-strapi-'));
+        const clientDir = join(dir, 'src', 'lib', 'strapi-api');
+        mkdirSync(clientDir, { recursive: true });
+        writeFileSync(join(clientDir, 'base.ts'), 'export async function req(url: string, init: RequestInit) {\n  const response = await fetch(url, init);\n  return response;\n}\n');
+        writeFileSync(join(clientDir, 'other.ts'), 'export const x = 1;\n');
+        const result = wireStrapiClient(dir, clientDir, schemas);
+        expect(result.wired).toBe(true);
+        const generated = readFileSync(join(clientDir, 'fimo-strapi.ts'), 'utf8');
+        expect(generated).toContain('createFimoStrapiFetch');
+        expect(generated).toContain("'blog-posts': 'BlogPost',");
+        const base = readFileSync(join(clientDir, 'base.ts'), 'utf8');
+        expect(base).toContain('await fimoStrapiFetch(url, init)');
+        expect(base).not.toContain('await fetch(');
+        expect(base).toContain("import { fimoStrapiFetch } from './fimo-strapi';");
+        // A file with no fetch stays untouched.
+        expect(readFileSync(join(clientDir, 'other.ts'), 'utf8')).not.toContain('fimoStrapiFetch');
+    });
+    it('warns when no bare fetch is found', () => {
+        dir = mkdtempSync(join(tmpdir(), 'wire-strapi-none-'));
+        const clientDir = join(dir, 'client');
+        mkdirSync(clientDir, { recursive: true });
+        writeFileSync(join(clientDir, 'base.ts'), 'export const x = 1;\n');
+        const result = wireStrapiClient(dir, clientDir, schemas);
+        expect(result.wired).toBe(false);
+        expect(result.warnings[0]).toContain('No bare fetch()');
+    });
+});

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,117 @@
+/**
+ * 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;
+    /** A single-document type (e.g. a Strapi singleType) → true; a collection → 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;
+    /**
+     * Enumerate the frontend's remaining couplings to this CMS — the unwire
+     * worklist and the cutover gate (`clean`). Keys on actual CMS references, not
+     * filenames, so a client module rewritten to call Fimo reads as clean.
+     * Returns undefined for a connector without touchpoint detection.
+     */
+    detectTouchpoints?(cwd: string): CmsTouchpoints;
+}
+export interface CmsWireResult {
+    changes: string[];
+    warnings: string[];
+    wired: boolean;
+}
+export interface CmsTouchpointSite {
+    file: string;
+    line: number;
+    reason: string;
+    snippet: string;
+}
+export interface CmsTouchpoints {
+    /** SDK/client/type packages still declared in the frontend's package.json. */
+    dependencies: string[];
+    /** Source lines that still reach the CMS at runtime. */
+    callSites: CmsTouchpointSite[];
+    /** CMS base-URL / token env keys still present in dotenv files. */
+    envVars: string[];
+    /** No runtime coupling remains — the cutover is complete. */
+    clean: 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 {};