fimo 2.6.0 → 2.7.0-experimental.1

package/dist/runtime/paths/get-fimo-paths.d.ts

@@ -6,7 +6,9 @@ import type { FimoPath, GetFimoPathsOptions } from './types.js';
  *
  * - Static paths in config: emitted as-is.
  * - Dynamic paths (with `:slug`-style entry params): expanded by fetching
- *   schema entries from `VITE_API_URL`. One returned entry per expansion.
+ *   every schema entry from `VITE_API_URL`, page by page. One path per entry.
+ * - A route with an external param is never emitted: the application owns
+ *   those values and lists those URLs itself.
  * - Locales come from the route contract, not from the project locale list: a
  *   route is emitted once per locale only when its path declares a `:locale`
  *   segment. The default locale is always unprefixed. A route without a

package/dist/runtime/paths/get-fimo-paths.js

@@ -11,6 +11,9 @@ const isValidationBuild = !!process.env.FIMO_VALIDATION_BUILD;
 const MAX_FETCH_ATTEMPTS = 3;
 const RETRYABLE_FETCH_STATUSES = new Set([502, 503, 504]);
 const RETRY_BASE_DELAY_MS = 250;
+// The content API pages with `limit` (capped at 100) and `offset`; its
+// `meta.hasMore` says whether another page follows.
+const ENTRIES_PAGE_SIZE = 100;
 function readEnvValue(rootDir, key) {
     if (process.env[key]) {
         return process.env[key];
@@ -42,9 +45,6 @@ function resolveApiBaseUrl(rootDir) {
 async function fetchEntries(baseUrl, schema, rootDir, locale) {
     const url = new URL(`${baseUrl.replace(/\/$/, '')}/entries/${schema}`);
     url.searchParams.set('locale', locale);
-    if (isValidationBuild) {
-        url.searchParams.set('limit', '1');
-    }
     const headers = {};
     // `FIMO_ENV` is a customer-facing variable name and keeps its spelling; the
     // header this build emits is canonical. A
@@ -54,11 +54,47 @@ async function fetchEntries(baseUrl, schema, rootDir, locale) {
     if (branch) {
         headers['X-Fimo-Branch'] = branch;
     }
+    // A validation build only proves the route expands, so one entry is enough.
+    if (isValidationBuild) {
+        url.searchParams.set('limit', '1');
+        return (await fetchEntriesPage(url, headers, schema)).data;
+    }
+    // Every entry becomes a URL, so walk the whole collection page by page.
+    const entries = [];
+    let offset = 0;
+    for (;;) {
+        const pageUrl = new URL(url);
+        pageUrl.searchParams.set('limit', String(ENTRIES_PAGE_SIZE));
+        pageUrl.searchParams.set('offset', String(offset));
+        const page = await fetchEntriesPage(pageUrl, headers, schema);
+        entries.push(...page.data);
+        if (!page.meta) {
+            // Without pagination metadata a short page is the whole collection; a
+            // full one may hide more entries, and a truncated list is a silent bug.
+            if (page.data.length >= ENTRIES_PAGE_SIZE) {
+                throw new Error(`Entries response for ${schema} returned ${page.data.length} rows without pagination metadata, so every path cannot be enumerated.`);
+            }
+            return entries;
+        }
+        if (!page.meta.hasMore) {
+            return entries;
+        }
+        const nextOffset = page.meta.offset + page.meta.limit;
+        if (nextOffset <= offset) {
+            throw new Error(`Entries pagination for ${schema} did not advance past offset ${offset}.`);
+        }
+        offset = nextOffset;
+    }
+}
+async function fetchEntriesPage(url, headers, schema) {
     for (let attempt = 1; attempt <= MAX_FETCH_ATTEMPTS; attempt += 1) {
         const res = await fetch(url, { headers });
         if (res.ok) {
             const payload = (await res.json());
-            return Array.isArray(payload?.data) ? payload.data : [];
+            return {
+                data: Array.isArray(payload?.data) ? payload.data : [],
+                meta: readPageMeta(payload?.meta),
+            };
         }
         if (!RETRYABLE_FETCH_STATUSES.has(res.status) || attempt === MAX_FETCH_ATTEMPTS) {
             const attemptDetail = attempt > 1 ? ` after ${attempt} attempts` : '';
@@ -68,6 +104,16 @@ async function fetchEntries(baseUrl, schema, rootDir, locale) {
     }
     throw new Error(`Failed to fetch ${schema}`);
 }
+function readPageMeta(meta) {
+    if (!meta || typeof meta !== 'object') {
+        return undefined;
+    }
+    const { limit, offset, hasMore } = meta;
+    if (typeof limit !== 'number' || typeof offset !== 'number' || typeof hasMore !== 'boolean') {
+        return undefined;
+    }
+    return { limit, offset, hasMore };
+}
 // Glob-ish matcher for route keys: '*' matches one segment, '**' matches any.
 function compilePattern(pattern) {
     const escaped = pattern
@@ -87,7 +133,9 @@ function matchesAny(routeKey, patterns) {
  *
  * - Static paths in config: emitted as-is.
  * - Dynamic paths (with `:slug`-style entry params): expanded by fetching
- *   schema entries from `VITE_API_URL`. One returned entry per expansion.
+ *   every schema entry from `VITE_API_URL`, page by page. One path per entry.
+ * - A route with an external param is never emitted: the application owns
+ *   those values and lists those URLs itself.
  * - Locales come from the route contract, not from the project locale list: a
  *   route is emitted once per locale only when its path declares a `:locale`
  *   segment. The default locale is always unprefixed. A route without a
@@ -125,6 +173,12 @@ export async function getFimoPaths(opts = {}) {
         if (contract.unresolvedParams.length > 0) {
             return false;
         }
+        // Values the application owns cannot be enumerated here. The app lists
+        // those URLs itself — React Router `prerender`, Next `generateStaticParams`
+        // — and concatenates them with this result.
+        if (contract.externalParams.length > 0) {
+            return false;
+        }
         if (opts.include && opts.include.length > 0 && !matchesAny(contract.id, opts.include)) {
             return false;
         }

package/dist/runtime/primitives/lib/primitives.d.ts

@@ -98,7 +98,24 @@ export declare class FimoMedia {
     get __fimo(): FimoSource;
 }
 /**
- * FimoBoolean - Boolean with source tracking (for display purposes)
+ * FimoBoolean - a boolean with source tracking.
+ *
+ * Read `.value` before any condition, comparison, attribute, or third-party
+ * call, and pass the wrapper itself to `<Boolean>` so Studio keeps the edit
+ * target.
+ *
+ * `if (entry.featured)` is ALWAYS true, including for `false`, because the
+ * wrapper is an object. That is a language rule, not a gap to close here:
+ * `ToBoolean` on an object never consults `valueOf`, `Symbol.toPrimitive`, a
+ * `Boolean` subclass, or a `Proxy`, and TypeScript reports nothing (it
+ * special-cases only Promises and functions). Removing the wrapper is the only
+ * real fix; do not add a coercion hook that appears to solve it.
+ *
+ * `toString` and `toJSON` cover the two boundaries that DO give us a hook, so
+ * the wrapper stops leaking there: `${flag}` reads `"true"`/`"false"` instead
+ * of `"[object Object]"`, and `JSON.stringify` emits `false` instead of
+ * `{"value":false}` — a payload that rehydrates as a permanently truthy object.
+ * Framework boundaries still use `serializeContent`, which also drops metadata.
  */
 export declare class FimoBoolean {
     readonly value: boolean;
@@ -107,6 +124,8 @@ export declare class FimoBoolean {
     constructor(value: boolean, source: string, context?: FimoSourceContext);
     get __fimo(): FimoSource;
     valueOf(): boolean;
+    toString(): string;
+    toJSON(): boolean;
 }
 /**
  * Tiptap JSONContent structure for rich text

package/dist/runtime/primitives/lib/primitives.js

@@ -180,7 +180,24 @@ export class FimoMedia {
 }
 _f = FIMO_SOURCE, _g = FIMO_SOURCE_CONTEXT;
 /**
- * FimoBoolean - Boolean with source tracking (for display purposes)
+ * FimoBoolean - a boolean with source tracking.
+ *
+ * Read `.value` before any condition, comparison, attribute, or third-party
+ * call, and pass the wrapper itself to `<Boolean>` so Studio keeps the edit
+ * target.
+ *
+ * `if (entry.featured)` is ALWAYS true, including for `false`, because the
+ * wrapper is an object. That is a language rule, not a gap to close here:
+ * `ToBoolean` on an object never consults `valueOf`, `Symbol.toPrimitive`, a
+ * `Boolean` subclass, or a `Proxy`, and TypeScript reports nothing (it
+ * special-cases only Promises and functions). Removing the wrapper is the only
+ * real fix; do not add a coercion hook that appears to solve it.
+ *
+ * `toString` and `toJSON` cover the two boundaries that DO give us a hook, so
+ * the wrapper stops leaking there: `${flag}` reads `"true"`/`"false"` instead
+ * of `"[object Object]"`, and `JSON.stringify` emits `false` instead of
+ * `{"value":false}` — a payload that rehydrates as a permanently truthy object.
+ * Framework boundaries still use `serializeContent`, which also drops metadata.
  */
 export class FimoBoolean {
     constructor(value, source, context) {
@@ -212,6 +229,12 @@ export class FimoBoolean {
     valueOf() {
         return this.value;
     }
+    toString() {
+        return String(this.value);
+    }
+    toJSON() {
+        return this.value;
+    }
 }
 _h = FIMO_SOURCE, _j = FIMO_SOURCE_CONTEXT;
 /**

package/dist/runtime/routes/index.d.ts

@@ -11,7 +11,12 @@ export interface FimoRouteSeoConfig {
     siteName?: string;
 }
 export interface FimoRouteParamConfig<Query = unknown> {
-    type?: 'entry' | 'locale';
+    /**
+     * Omitted means `'entry'`; the reserved name `locale` infers `'locale'`.
+     * `'external'` marks a placeholder whose values the application owns: it is
+     * matched from URLs but never looked up in the CMS and never enumerated.
+     */
+    type?: 'entry' | 'locale' | 'external';
     schema?: string;
     queryField?: string;
     displayField?: string;
@@ -67,7 +72,16 @@ export interface FimoLocaleParam {
      */
     optional: boolean;
 }
-export type FimoRouteParam = FimoEntryParam | FimoLocaleParam;
+/**
+ * A placeholder whose values the application owns: a synced catalogue, a
+ * browser-only id, a computed segment. Never read from the CMS, never
+ * enumerated by Fimo.
+ */
+export interface FimoExternalParam {
+    type: 'external';
+    name: string;
+}
+export type FimoRouteParam = FimoEntryParam | FimoLocaleParam | FimoExternalParam;
 export interface FimoRouteIssue {
     /** The parameter the issue is about, when it is about one. */
     param?: string;
@@ -85,6 +99,8 @@ export interface FimoRouteContract<RouteConfig extends FimoRouteConfig = FimoRou
     canonicalPath: string;
     params: FimoRouteParam[];
     entryParams: FimoEntryParam[];
+    /** Params the application owns. Non-empty means Fimo cannot enumerate this route's URLs. */
+    externalParams: FimoExternalParam[];
     localeParam: FimoLocaleParam | null;
     /** Placeholders in the path that no usable descriptor resolves. */
     unresolvedParams: string[];
@@ -120,7 +136,7 @@ export declare function hasLocaleSegment(path: string): boolean;
  * Normalize one declared route into the contract every consumer reads.
  *
  * Parameter types resolve in this order:
- * 1. an explicit `type`;
+ * 1. an explicit `type` (`entry`, `locale`, or `external`);
  * 2. the reserved name `locale`, which infers the locale type;
  * 3. otherwise the entry type, which is what every route written before
  *    locale-aware routing existed relies on.

package/dist/runtime/routes/index.js

@@ -85,6 +85,26 @@ function buildLocaleParam(name, descriptor, index, issues) {
   }
   return { type: "locale", name, optional: descriptor?.optional !== false };
 }
+function buildExternalParam(name, descriptor, issues) {
+  if (name === FIMO_LOCALE_PARAM) {
+    issues.push({
+      param: name,
+      message: `Param "${name}" is reserved for the locale segment and cannot use \`"type": "external"\`.`,
+      fix: `Drop \`"type": "external"\` from \`params.${name}\`, or rename the segment.`
+    });
+    return null;
+  }
+  for (const field of ["schema", "queryField", "displayField", "query", "optional"]) {
+    if (descriptor[field] !== void 0) {
+      issues.push({
+        param: name,
+        message: `External param "${name}" must not declare "${field}" \u2014 its values are owned by the application, never read from the CMS.`,
+        fix: `Remove "${field}" from \`params.${name}\`.`
+      });
+    }
+  }
+  return { type: "external", name };
+}
 function buildEntryParam(name, descriptor, issues) {
   if (name === FIMO_LOCALE_PARAM) {
     issues.push({
@@ -153,7 +173,8 @@ function resolveRouteContract(id, route) {
     }
     seen.add(name);
     const descriptor = declared[name];
-    const resolved = resolveParamType(name, descriptor) === "locale" ? buildLocaleParam(name, descriptor, index, issues) : buildEntryParam(name, descriptor, issues);
+    const type = resolveParamType(name, descriptor);
+    const resolved = type === "locale" ? buildLocaleParam(name, descriptor, index, issues) : type === "external" && descriptor ? buildExternalParam(name, descriptor, issues) : buildEntryParam(name, descriptor, issues);
     if (resolved) {
       params.push(resolved);
     } else {
@@ -178,6 +199,7 @@ function resolveRouteContract(id, route) {
     canonicalPath,
     params,
     entryParams: params.filter((param) => param.type === "entry"),
+    externalParams: params.filter((param) => param.type === "external"),
     localeParam,
     unresolvedParams,
     issues
@@ -217,6 +239,7 @@ function matchContract(urlSegments, contract, vocabulary) {
   }
   const params = {};
   const entryParams = {};
+  const entryNames = new Set(contract.entryParams.map((param) => param.name));
   let localeFromPath = null;
   let score = 0;
   let offset = 0;
@@ -244,7 +267,9 @@ function matchContract(urlSegments, contract, vocabulary) {
       const rawValue = catchAll ? urlSegments.slice(index + offset).join("/") : value;
       const decoded = safeDecode(rawValue);
       params[name] = decoded;
-      entryParams[name] = decoded;
+      if (entryNames.has(name)) {
+        entryParams[name] = decoded;
+      }
       if (catchAll) {
         break;
       }

package/dist/runtime/templates.d.ts

@@ -76,7 +76,7 @@ export declare function rewriteFimoValidateCommand(pkg: PkgWithScripts, pin?: st
  * only the ones it uses; every pin is derived from the `fimo` pin so the
  * platform keeps a single version selector (FIMO-1635).
  */
-export declare const FIMO_PACKAGES: readonly ['fimo', 'fimo-sveltekit', 'fimo-astro', 'fimo-vite', 'fimo-react', 'fimo-react-router', 'fimo-next'];
+export declare const FIMO_PACKAGES: readonly ['fimo-analytics', 'fimo', 'fimo-sveltekit', 'fimo-astro', 'fimo-vite', 'fimo-react', 'fimo-react-router', 'fimo-next'];
 export type FimoPackage = (typeof FIMO_PACKAGES)[number];
 /**
  * Pin for a companion package given the `fimo` pin. Semver and dist-tags carry

package/dist/runtime/templates.js

@@ -191,6 +191,7 @@ export function rewriteFimoValidateCommand(pkg, pin = resolveFimoPin()) {
  * platform keeps a single version selector (FIMO-1635).
  */
 export const FIMO_PACKAGES = [
+    'fimo-analytics',
     'fimo',
     'fimo-sveltekit',
     'fimo-astro',

package/dist/scripts/validate-page-registry.js

@@ -1,6 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { pageSourceParamExpressions, parsePageParamExpression, } from '@fimo/api-contracts';
+import { isEntryParamBinding, pageSourceParamExpressions, parsePageParamExpression, } from '@fimo/api-contracts';
+/** Only an entry binding names content; the rest declare where values come from. */
+function isEntryBinding(binding) {
+    return isEntryParamBinding(binding);
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -74,7 +78,14 @@ function validateQuery(query, pointer, schema, params, schemas) {
     for (const expression of pageSourceParamExpressions(query)) {
         const parsed = parsePageParamExpression(expression);
         const binding = parsed ? params[parsed.param] : undefined;
-        if (!parsed || !binding || typeof binding.schema !== 'string') {
+        if (!parsed || !binding) {
+            continue;
+        }
+        if (!isEntryBinding(binding)) {
+            errors.push(`${pointer}: ${expression} reads param "${parsed.param}", which is not a Collection entry param.`);
+            continue;
+        }
+        if (typeof binding.schema !== 'string') {
             continue;
         }
         const boundSchema = schemas.get(binding.schema);
@@ -99,7 +110,7 @@ export function validatePageRegistrySchemaReferences(cwd, config, displayPath) {
         const params = isRecord(rawRoute.params) ? rawRoute.params : {};
         for (const [param, binding] of Object.entries(params)) {
             const pointer = `${displayPath}#routes.${routeId}.params.${param}`;
-            if (typeof binding.schema !== 'string') {
+            if (!isEntryBinding(binding) || typeof binding.schema !== 'string') {
                 continue;
             }
             const schema = schemas.get(binding.schema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "2.6.0",
+  "version": "2.7.0-experimental.1",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "keywords": [
     "astro-component"
@@ -165,7 +165,8 @@
   "scripts": {
     "build": "pnpm run clean && tsc -b tsconfig.json && chmod +x dist/cli/index.js",
     "build:bundle": "node scripts/bundle-cli.mjs && node scripts/bundle-routes.mjs",
-    "check:types": "tsc -b tsconfig.json && tsc -p tsconfig.test.json",
+    "check:types": "tsc -b tsconfig.json && tsc -p tsconfig.test.json && pnpm check:types:guardrails",
+    "check:types:guardrails": "tsc -p tsconfig.guardrails.json",
     "start": "tsx src/cli/index.ts",
     "install-cli": "pnpm build && node scripts/install-cli.mjs",
     "publish-cli": "node scripts/publish-tarball.mjs",
@@ -193,13 +194,13 @@
   "devDependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
-    "@fimo/agents-bundle": "2.6.0",
-    "@fimo/api-contracts": "2.6.0",
-    "@fimo/cli-kit": "2.6.0",
-    "@fimo/framework-detect": "2.6.0",
-    "@fimo/routes": "2.6.0",
-    "@fimo/sdk": "2.6.0",
-    "@fimo/tsconfig": "2.6.0",
+    "@fimo/agents-bundle": "2.7.0-experimental.1",
+    "@fimo/api-contracts": "2.7.0-experimental.1",
+    "@fimo/cli-kit": "2.7.0-experimental.1",
+    "@fimo/framework-detect": "2.7.0-experimental.1",
+    "@fimo/routes": "2.7.0-experimental.1",
+    "@fimo/sdk": "2.7.0-experimental.1",
+    "@fimo/tsconfig": "2.7.0-experimental.1",
     "@types/node": "22.18.6",
     "agent-install": "^0.0.5",
     "astro": "^7.1.6",

package/release.json

@@ -1,5 +1,5 @@
 {
   "source": "npm",
-  "apiUrl": "https://api.fimo.ai",
-  "webUrl": "https://fimo.ai"
+  "apiUrl": "https://api.staging.fimo.team",
+  "webUrl": "https://staging.fimo.team"
 }

package/templates/astro/package.json

@@ -9,8 +9,8 @@
     "check": "astro sync && astro check"
   },
   "dependencies": {
-    "fimo": "2.6.0",
-    "fimo-astro": "2.6.0"
+    "fimo": "2.7.0-experimental.1",
+    "fimo-astro": "2.7.0-experimental.1"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/templates/nextjs/package.json

@@ -12,9 +12,9 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.80.6",
-    "fimo": "2.6.0",
-    "fimo-next": "2.6.0",
-    "fimo-react": "2.6.0",
+    "fimo": "2.7.0-experimental.1",
+    "fimo-next": "2.7.0-experimental.1",
+    "fimo-react": "2.7.0-experimental.1",
     "next": "^16.3.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"

package/templates/react-router/package.json

@@ -21,10 +21,10 @@
     "cn": "0.2.4",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "2.6.0",
-    "fimo-react": "2.6.0",
-    "fimo-react-router": "2.6.0",
-    "fimo-vite": "2.6.0",
+    "fimo": "2.7.0-experimental.1",
+    "fimo-react": "2.7.0-experimental.1",
+    "fimo-react-router": "2.7.0-experimental.1",
+    "fimo-vite": "2.7.0-experimental.1",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/sveltekit/package.json

@@ -11,8 +11,8 @@
     "prepare": "svelte-kit sync"
   },
   "dependencies": {
-    "fimo": "2.6.0",
-    "fimo-sveltekit": "2.6.0"
+    "fimo": "2.7.0-experimental.1",
+    "fimo-sveltekit": "2.7.0-experimental.1"
   },
   "devDependencies": {
     "@sveltejs/kit": "^2.70.2",

package/templates/vite/package.json

@@ -11,10 +11,10 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.80.6",
-    "fimo": "2.6.0",
-    "fimo-react": "2.6.0",
-    "fimo-react-router": "2.6.0",
-    "fimo-vite": "2.6.0",
+    "fimo": "2.7.0-experimental.1",
+    "fimo-react": "2.7.0-experimental.1",
+    "fimo-react-router": "2.7.0-experimental.1",
+    "fimo-vite": "2.7.0-experimental.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-router": "^8.3.0"