fimo 0.7.0-experimental.2 → 0.7.0-experimental.4

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

@@ -0,0 +1,3 @@
+import type { CmsConnector } from '../types.js';
+/** Assemble the Strapi connector for a wrapped frontend, or null if no Strapi. */
+export declare function strapiConnector(frontendDir: string): CmsConnector | null;

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

@@ -0,0 +1,15 @@
+import { detectStrapi } from './detect.js';
+import { renderStrapiListSource } from './list-source.js';
+import { readStrapiSchemas } from './schema-map.js';
+/** Assemble the Strapi connector for a wrapped frontend, or null if no Strapi. */
+export function strapiConnector(frontendDir) {
+    const detection = detectStrapi(frontendDir);
+    if (!detection) {
+        return null;
+    }
+    return {
+        detection,
+        readSchemas: () => (detection.appDir ? readStrapiSchemas(detection.appDir) : []),
+        renderListSource: (schemas, serverImport) => schemas.length > 0 ? renderStrapiListSource(schemas, serverImport) : null,
+    };
+}

package/dist/scripts/cms/strapi/list-source.d.ts

@@ -0,0 +1,17 @@
+import type { CmsCollectionSchema } from '../types.js';
+/**
+ * Emit a GENERIC Strapi-list read helper as source text. The scaffold pushes a
+ * CMS model + example content into Fimo; this helper lets a site's LIST views
+ * render that example content from Fimo (detail views + dynamic zones stay on
+ * the CMS). It is intentionally best-effort and site-neutral — the agent drops
+ * it in and wires the site's list fetchers to it (the non-deterministic last
+ * mile the machine can't own).
+ *
+ * The reshape is grounded in the Fimo runtime contract (`fetchEntries` →
+ * `{ id, data }`, media fields `{ url, ... }`, richtext fields a ProseMirror
+ * doc): richtext docs are flattened to plain text (so list helpers like a
+ * read-time estimate that expect a string don't choke), media and scalars pass
+ * through, and an empty Fimo result returns null so the caller falls back to
+ * the live CMS.
+ */
+export declare function renderStrapiListSource(schemas: CmsCollectionSchema[], serverImport: string): string;

package/dist/scripts/cms/strapi/list-source.js

@@ -0,0 +1,90 @@
+/**
+ * Emit a GENERIC Strapi-list read helper as source text. The scaffold pushes a
+ * CMS model + example content into Fimo; this helper lets a site's LIST views
+ * render that example content from Fimo (detail views + dynamic zones stay on
+ * the CMS). It is intentionally best-effort and site-neutral — the agent drops
+ * it in and wires the site's list fetchers to it (the non-deterministic last
+ * mile the machine can't own).
+ *
+ * The reshape is grounded in the Fimo runtime contract (`fetchEntries` →
+ * `{ id, data }`, media fields `{ url, ... }`, richtext fields a ProseMirror
+ * doc): richtext docs are flattened to plain text (so list helpers like a
+ * read-time estimate that expect a string don't choke), media and scalars pass
+ * through, and an empty Fimo result returns null so the caller falls back to
+ * the live CMS.
+ */
+export function renderStrapiListSource(schemas, serverImport) {
+    const entries = schemas
+        .filter((schema) => !schema.isSingleton)
+        .map((schema) => `  '${schema.sourceUid}': '${schema.name}',`)
+        .join('\n');
+    return `// AUTO-GENERATED by \`fimo migrate --scaffold-cms\`. Renders the CMS collections
+// scaffolded into Fimo (EXAMPLE content) for LIST views, so pages show the fake
+// content from Fimo while detail views and dynamic zones stay on your CMS.
+//
+// Wire your CMS client's list methods to this (see the migration prompt), e.g.
+// inside fetchMany/fetchAll:  const fimo = await fimoCmsList(uid, { limit });
+//                             if (fimo) return fimo;
+// Best-effort and generic by design — adjust per component as needed.
+import { fetchEntries } from '${serverImport}';
+
+// Strapi content-type UID -> Fimo type name (from the scaffold).
+const FIMO_TYPES: Record<string, string> = {
+${entries}
+};
+
+function docToText(node: unknown): string {
+  if (!node || typeof node !== 'object') {
+    return '';
+  }
+  const record = node as { text?: unknown; content?: unknown };
+  if (typeof record.text === 'string') {
+    return record.text;
+  }
+  if (Array.isArray(record.content)) {
+    return record.content.map(docToText).join(' ');
+  }
+  return '';
+}
+
+function reshapeValue(value: unknown): unknown {
+  // Richtext is a ProseMirror doc -> flatten to plain text so string consumers
+  // (excerpts, read-time) are safe. Media { url, ... } and scalars pass through.
+  if (value && typeof value === 'object' && (value as { type?: unknown }).type === 'doc') {
+    return docToText(value);
+  }
+  return value;
+}
+
+function reshape(data: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    out[key] = reshapeValue(value);
+  }
+  return out;
+}
+
+/**
+ * A Strapi-v5-shaped list envelope built from the scaffolded Fimo content, or
+ * null when nothing was scaffolded for this UID (fall back to the live CMS).
+ */
+export async function fimoCmsList(
+  uid: string,
+  options: { limit?: number } = {}
+): Promise<{ data: Record<string, unknown>[]; meta: { pagination: Record<string, number> } } | null> {
+  const typeName = FIMO_TYPES[uid];
+  if (!typeName) {
+    return null;
+  }
+  const entries = await fetchEntries(typeName, options.limit ? { limit: options.limit } : {});
+  if (entries.length === 0) {
+    return null;
+  }
+  const data = entries.map((entry) => ({ id: entry.id, documentId: entry.id, ...reshape(entry.data) }));
+  return {
+    data,
+    meta: { pagination: { page: 1, pageSize: data.length, pageCount: 1, total: data.length } },
+  };
+}
+`;
+}

package/dist/scripts/cms/strapi/list-source.test.d.ts

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

package/dist/scripts/cms/strapi/list-source.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { renderStrapiListSource } from './list-source.js';
+const schema = (name, sourceUid, isSingleton = false) => ({
+    name,
+    label: name,
+    isSingleton,
+    localized: false,
+    fields: {},
+    sourceUid,
+    sourcePath: `/${name.toLowerCase()}`,
+});
+describe('renderStrapiListSource', () => {
+    it('emits a helper importing fetchEntries with a uid→type map for collections only', () => {
+        const src = renderStrapiListSource([
+            schema('BlogPost', 'api::blog-post.blog-post'),
+            schema('PostTag', 'api::post-tag.post-tag'),
+            schema('Global', 'api::global.global', true),
+        ], 'fimo/next/server');
+        expect(src).toContain("import { fetchEntries } from 'fimo/next/server';");
+        expect(src).toContain("'api::blog-post.blog-post': 'BlogPost',");
+        expect(src).toContain("'api::post-tag.post-tag': 'PostTag',");
+        // Singletons have no list view — excluded from the map.
+        expect(src).not.toContain('api::global.global');
+        expect(src).toContain('export async function fimoCmsList(');
+        // Richtext flattening + fallback-to-CMS contract are present.
+        expect(src).toContain('docToText');
+        expect(src).toContain('return null');
+    });
+    it('threads the framework server import through', () => {
+        const src = renderStrapiListSource([schema('Cms', 'api::cms.cms')], 'fimo/astro/server');
+        expect(src).toContain("import { fetchEntries } from 'fimo/astro/server';");
+    });
+});

package/dist/scripts/cms/strapi/schema-map.d.ts

@@ -0,0 +1,9 @@
+import type { CmsCollectionSchema } from '../types.js';
+/** `blog-post` / `blog_posts` / `Blog Post` → `BlogPost`. */
+export declare function pascalCase(name: string): string;
+/**
+ * Read every local Strapi content-type schema into the Fimo schema shape.
+ * Two passes: first name every type (so relation targets resolve to Fimo
+ * names), then map fields.
+ */
+export declare function readStrapiSchemas(strapiAppDir: string): CmsCollectionSchema[];

package/dist/scripts/cms/strapi/schema-map.js

@@ -0,0 +1,138 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const TO_MANY = new Set(['oneToMany', 'manyToMany']);
+/** `blog-post` / `blog_posts` / `Blog Post` → `BlogPost`. */
+export function pascalCase(name) {
+    return name
+        .replace(/[^a-zA-Z0-9]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+        .replace(/^(.)/, (c) => c.toUpperCase());
+}
+/**
+ * Map one Strapi attribute to a Fimo field. Returns `null` for fields Fimo does
+ * not model as content (the slug uid, passwords). Relations to imported types
+ * become references; relations to non-imported targets (users, plugins) and
+ * structural fields (components, dynamic zones) fall back to `json` so example
+ * content round-trips and never dangles.
+ */
+function mapAttribute(field, attr, uidToName) {
+    if (field === 'slug') {
+        // Fimo reserves `slug` as entry metadata (set inside the row data).
+        return null;
+    }
+    switch (attr.type) {
+        case 'password':
+            return null;
+        case 'string':
+        case 'text':
+        case 'email':
+        case 'uid':
+        case 'enumeration':
+            return { type: 'string' };
+        case 'richtext':
+        case 'blocks':
+            return { type: 'richtext' };
+        case 'integer':
+        case 'biginteger':
+        case 'decimal':
+        case 'float':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'date':
+        case 'datetime':
+        case 'time':
+        case 'timestamp':
+            return { type: 'date' };
+        case 'media':
+            return { type: 'media' };
+        case 'json':
+        case 'component':
+        case 'dynamiczone':
+            return { type: 'json' };
+        case 'relation': {
+            const targetName = attr.target ? uidToName.get(attr.target) : undefined;
+            if (!targetName) {
+                // Relation to a non-imported target (users-permissions, other plugins).
+                return { type: 'json' };
+            }
+            const many = attr.relation ? TO_MANY.has(attr.relation) : false;
+            return many ? { type: 'reference', target: targetName, many: true } : { type: 'reference', target: targetName };
+        }
+        default:
+            // Unknown/custom attribute — never crash; keep the value verbatim.
+            return { type: 'json' };
+    }
+}
+function mapSchema(raw, uidToName) {
+    const info = raw.schema.info ?? {};
+    const name = uidToName.get(raw.uid);
+    const fields = {};
+    for (const [field, attr] of Object.entries(raw.schema.attributes ?? {})) {
+        const mapped = mapAttribute(field, attr, uidToName);
+        if (mapped) {
+            fields[field] = mapped;
+        }
+    }
+    return {
+        name,
+        label: info.displayName || name,
+        isSingleton: raw.schema.kind === 'singleType',
+        localized: raw.schema.pluginOptions?.i18n?.localized === true,
+        fields,
+        sourceUid: raw.uid,
+        sourcePath: `/${info.pluralName ?? raw.contentTypeName}`,
+    };
+}
+/** Walk `<strapiAppDir>/src/api/<api>/content-types/<ct>/schema.json`. */
+function collectRawSchemas(strapiAppDir) {
+    const apiDir = join(strapiAppDir, 'src', 'api');
+    if (!existsSync(apiDir)) {
+        return [];
+    }
+    const raws = [];
+    for (const apiEntry of readdirSync(apiDir, { withFileTypes: true })) {
+        if (!apiEntry.isDirectory()) {
+            continue;
+        }
+        const ctRoot = join(apiDir, apiEntry.name, 'content-types');
+        if (!existsSync(ctRoot)) {
+            continue;
+        }
+        for (const ctEntry of readdirSync(ctRoot, { withFileTypes: true })) {
+            if (!ctEntry.isDirectory()) {
+                continue;
+            }
+            const schemaPath = join(ctRoot, ctEntry.name, 'schema.json');
+            if (!existsSync(schemaPath)) {
+                continue;
+            }
+            try {
+                const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+                raws.push({
+                    uid: `api::${apiEntry.name}.${ctEntry.name}`,
+                    apiName: apiEntry.name,
+                    contentTypeName: ctEntry.name,
+                    schema,
+                });
+            }
+            catch {
+                // Malformed schema.json — skip, never abort the whole import.
+            }
+        }
+    }
+    return raws;
+}
+/**
+ * Read every local Strapi content-type schema into the Fimo schema shape.
+ * Two passes: first name every type (so relation targets resolve to Fimo
+ * names), then map fields.
+ */
+export function readStrapiSchemas(strapiAppDir) {
+    const raws = collectRawSchemas(strapiAppDir);
+    const uidToName = new Map();
+    for (const raw of raws) {
+        const singular = raw.schema.info?.singularName ?? raw.contentTypeName;
+        uidToName.set(raw.uid, pascalCase(singular));
+    }
+    return raws.map((raw) => mapSchema(raw, uidToName)).sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/scripts/cms/strapi/schema-map.test.d.ts

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

package/dist/scripts/cms/strapi/schema-map.test.js

@@ -0,0 +1,87 @@
+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 { readStrapiSchemas } from './schema-map.js';
+let dir;
+function writeSchema(apiName, ctName, schema) {
+    const ctDir = join(dir, 'src', 'api', apiName, 'content-types', ctName);
+    mkdirSync(ctDir, { recursive: true });
+    writeFileSync(join(ctDir, 'schema.json'), JSON.stringify(schema));
+}
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('readStrapiSchemas', () => {
+    it('maps Strapi attribute types to Fimo fields and resolves relations', () => {
+        dir = mkdtempSync(join(tmpdir(), 'strapi-schema-'));
+        writeSchema('blog-post', 'blog-post', {
+            kind: 'collectionType',
+            info: { singularName: 'blog-post', pluralName: 'blog-posts', displayName: 'Blog Post' },
+            pluginOptions: {},
+            attributes: {
+                title: { type: 'string', required: true },
+                slug: { type: 'uid', targetField: 'title' },
+                content: { type: 'richtext' },
+                readTime: { type: 'integer' },
+                featured: { type: 'boolean' },
+                publishedAt: { type: 'datetime' },
+                level: { type: 'enumeration', enum: ['a', 'b'] },
+                cover: { type: 'media' },
+                hero: { type: 'component', component: 'blocks.hero', repeatable: false },
+                sections: { type: 'dynamiczone', components: [] },
+                category: { type: 'relation', relation: 'manyToOne', target: 'api::post-category.post-category' },
+                tags: { type: 'relation', relation: 'manyToMany', target: 'api::post-tag.post-tag' },
+                author: { type: 'relation', relation: 'manyToOne', target: 'plugin::users-permissions.user' },
+            },
+        });
+        writeSchema('post-category', 'post-category', {
+            kind: 'collectionType',
+            info: { singularName: 'post-category', pluralName: 'post-categories', displayName: 'Post Category' },
+            attributes: { name: { type: 'string' }, slug: { type: 'uid' } },
+        });
+        writeSchema('post-tag', 'post-tag', {
+            kind: 'collectionType',
+            info: { singularName: 'post-tag', pluralName: 'post-tags', displayName: 'Post Tag' },
+            attributes: { name: { type: 'string' } },
+        });
+        writeSchema('global', 'global', {
+            kind: 'singleType',
+            info: { singularName: 'global', pluralName: 'globals', displayName: 'Global' },
+            pluginOptions: { i18n: { localized: true } },
+            attributes: { siteName: { type: 'string' } },
+        });
+        const schemas = readStrapiSchemas(dir);
+        expect(schemas.map((s) => s.name)).toEqual(['BlogPost', 'Global', 'PostCategory', 'PostTag']);
+        const blogPost = schemas.find((s) => s.name === 'BlogPost');
+        expect(blogPost.isSingleton).toBe(false);
+        expect(blogPost.localized).toBe(false);
+        expect(blogPost.sourceUid).toBe('api::blog-post.blog-post');
+        expect(blogPost.fields).toMatchObject({
+            title: { type: 'string' },
+            content: { type: 'richtext' },
+            readTime: { type: 'number' },
+            featured: { type: 'boolean' },
+            publishedAt: { type: 'date' },
+            level: { type: 'string' },
+            cover: { type: 'media' },
+            hero: { type: 'json' },
+            sections: { type: 'json' },
+            category: { type: 'reference', target: 'PostCategory' },
+            tags: { type: 'reference', target: 'PostTag', many: true },
+            author: { type: 'json' },
+        });
+        // slug is reserved entry metadata — never a schema field.
+        expect('slug' in blogPost.fields).toBe(false);
+        const global = schemas.find((s) => s.name === 'Global');
+        expect(global.isSingleton).toBe(true);
+        expect(global.localized).toBe(true);
+    });
+    it('returns an empty list when the app has no content types', () => {
+        dir = mkdtempSync(join(tmpdir(), 'strapi-schema-empty-'));
+        mkdirSync(join(dir, 'src'), { recursive: true });
+        expect(readStrapiSchemas(dir)).toEqual([]);
+    });
+});

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

@@ -0,0 +1,76 @@
+/**
+ * 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>;
+    /** 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;
+    /** 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;
+}

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);
+    });
+}