fimo 0.8.0 → 0.9.0-experimental.1

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

@@ -0,0 +1,31 @@
+export type StrapiCallReason = 'strapi-sdk-import' | 'env-ref' | 'uid-ref';
+export interface StrapiCallSite {
+    /** Path relative to the frontend directory. */
+    file: string;
+    line: number;
+    reason: StrapiCallReason;
+    snippet: string;
+}
+export interface StrapiTouchpoints {
+    /** Strapi SDK / client / generated-type packages still declared in package.json. */
+    dependencies: string[];
+    /** Source lines that still reach Strapi at runtime. */
+    callSites: StrapiCallSite[];
+    /** `STRAPI_*` keys still present in dotenv files (cleanup; low severity). */
+    envVars: string[];
+    /** No runtime Strapi coupling remains (no SDK deps, no call sites): the cutover is complete. */
+    clean: boolean;
+}
+/**
+ * Enumerate every remaining Strapi coupling in a wrapped frontend. This is the
+ * shared primitive behind both the unwire worklist (the agent's to-do) and the
+ * cutover gate (`clean === true`).
+ *
+ * `clean` is true when no runtime coupling remains — no Strapi SDK/client
+ * dependency and no source line that reaches Strapi — i.e. the site can no
+ * longer call Strapi. Detection keys on actual Strapi *references* (base-URL
+ * env, `api::` UID, SDK import), NOT filenames: a `lib/strapi.ts` the agent has
+ * rewritten to call Fimo has no Strapi references and therefore reads as clean.
+ * The `fimo/strapi` compat adapter is never counted.
+ */
+export declare function detectStrapiTouchpoints(frontendDir: string): StrapiTouchpoints;

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

@@ -0,0 +1,145 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const SOURCE_EXT_RE = /\.(tsx?|jsx?|mjs|cjs|astro|vue|svelte)$/;
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.turbo',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.vercel',
+    '.git',
+]);
+const MAX_FILES = 2000;
+/** A runtime reference to Strapi's base-URL / token env config. */
+const ENV_REF_RE = /\bSTRAPI[A-Z0-9_]*_URL\b|\bNEXT_PUBLIC_STRAPI[A-Z0-9_]*\b|\bSTRAPI[A-Z0-9_]*_TOKEN\b/;
+/** A Strapi content-type UID string (`api::article.article`). */
+const UID_REF_RE = /api::[a-z0-9-]+\.[a-z0-9-]+/;
+/** An import/require specifier — captured so a Strapi SDK can be told apart from `fimo/strapi`. */
+const IMPORT_RE = /(?:from\s+|require\(\s*|import\(\s*)['"`]([^'"`]+)['"`]/;
+/** A STRAPI env assignment in a dotenv file. */
+const ENV_KEY_RE = /^\s*([A-Z0-9_]*STRAPI[A-Z0-9_]*)\s*=/;
+function readDeps(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        return { ...pkg.dependencies, ...pkg.devDependencies };
+    }
+    catch {
+        return {};
+    }
+}
+function classifyLine(line) {
+    const importMatch = IMPORT_RE.exec(line);
+    // A Strapi SDK/client import — but NOT the `fimo/strapi` compat adapter.
+    if (importMatch && /strapi/i.test(importMatch[1]) && !/fimo/i.test(importMatch[1])) {
+        return 'strapi-sdk-import';
+    }
+    if (ENV_REF_RE.test(line)) {
+        return 'env-ref';
+    }
+    if (UID_REF_RE.test(line)) {
+        return 'uid-ref';
+    }
+    return null;
+}
+function scanCallSites(frontendDir) {
+    const sites = [];
+    let scanned = 0;
+    const walk = (dir) => {
+        if (scanned >= MAX_FILES) {
+            return;
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (scanned >= MAX_FILES) {
+                return;
+            }
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                    walk(join(dir, entry.name));
+                }
+                continue;
+            }
+            if (!SOURCE_EXT_RE.test(entry.name)) {
+                continue;
+            }
+            scanned += 1;
+            const full = join(dir, entry.name);
+            let text;
+            try {
+                text = readFileSync(full, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const lines = text.split('\n');
+            for (let i = 0; i < lines.length; i += 1) {
+                const reason = classifyLine(lines[i]);
+                if (reason) {
+                    sites.push({
+                        file: relative(frontendDir, full),
+                        line: i + 1,
+                        reason,
+                        snippet: lines[i].trim().slice(0, 200),
+                    });
+                }
+            }
+        }
+    };
+    walk(frontendDir);
+    return sites;
+}
+function scanEnvKeys(frontendDir) {
+    const keys = new Set();
+    for (const name of ['.env', '.env.local', '.env.development', '.env.production']) {
+        const file = join(frontendDir, name);
+        if (!existsSync(file)) {
+            continue;
+        }
+        try {
+            for (const line of readFileSync(file, 'utf8').split('\n')) {
+                const match = ENV_KEY_RE.exec(line);
+                if (match) {
+                    keys.add(match[1]);
+                }
+            }
+        }
+        catch {
+            // unreadable — ignore
+        }
+    }
+    return [...keys];
+}
+/**
+ * Enumerate every remaining Strapi coupling in a wrapped frontend. This is the
+ * shared primitive behind both the unwire worklist (the agent's to-do) and the
+ * cutover gate (`clean === true`).
+ *
+ * `clean` is true when no runtime coupling remains — no Strapi SDK/client
+ * dependency and no source line that reaches Strapi — i.e. the site can no
+ * longer call Strapi. Detection keys on actual Strapi *references* (base-URL
+ * env, `api::` UID, SDK import), NOT filenames: a `lib/strapi.ts` the agent has
+ * rewritten to call Fimo has no Strapi references and therefore reads as clean.
+ * The `fimo/strapi` compat adapter is never counted.
+ */
+export function detectStrapiTouchpoints(frontendDir) {
+    const dependencies = Object.keys(readDeps(frontendDir)).filter((name) => /strapi/i.test(name));
+    const callSites = scanCallSites(frontendDir);
+    const envVars = scanEnvKeys(frontendDir);
+    return {
+        dependencies,
+        callSites,
+        envVars,
+        clean: dependencies.length === 0 && callSites.length === 0,
+    };
+}

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/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,46 @@
+import { computeFieldShapes } from './shapes.js';
+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');
+    const fieldShapes = JSON.stringify(computeFieldShapes(schemas), null, 2);
+    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(', ')}];
+
+// Structural field shapes (single components read as objects; block items and
+// dynamic zones reshape into the Strapi shape the components expect).
+const FIELD_SHAPES = ${fieldShapes};
+
+export const fimoStrapiFetch = createFimoStrapiFetch({
+  types: TYPES,
+  singletons: SINGLETONS,
+  fieldShapes: FIELD_SHAPES,
+});
+`;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * 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;
+    /** Default applied when an entry omits the field (e.g. a baked block discriminator). */
+    readonly default?: unknown;
+    /** False hides the field from Studio editing (internal discriminators like `__component`). */
+    readonly editable?: boolean;
+}
+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;
+}
+/** One variant a `blocks` item may take — the Fimo shape of a source CMS
+ *  component. `uid` becomes the served block's `_type` (PascalCase, matches
+ *  `CONTENT_TYPE_NAME_PATTERN`). */
+export interface FimoBlockVariant {
+    readonly uid: string;
+    readonly label: string;
+    readonly fields: Record<string, FimoFieldDef>;
+}
+/** A blocks field's shape: one fixed shape (`fields`, a single/repeatable
+ *  component) or a discriminated union of variants (`oneOf`, a dynamic zone). */
+export type FimoBlocksSchema = {
+    readonly fields: Record<string, FimoFieldDef>;
+} | {
+    readonly oneOf: FimoBlockVariant[];
+};
+/** Ordered, Studio-editable structured content — the Fimo representation of a
+ *  CMS component (fixed) or dynamic zone (`oneOf`). The stored value is always
+ *  an array of `{ _key, [_type], ...fields }` items. */
+export interface FimoBlocksField {
+    readonly type: 'blocks';
+    readonly schema: FimoBlocksSchema;
+    readonly min?: number;
+    readonly max?: number;
+}
+export type FimoFieldDef = FimoScalarField | FimoReferenceField | FimoBlocksField;
+/**
+ * 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[];