fimo 0.18.0 → 0.20.0

package/dist/runtime/templates.js

@@ -164,6 +164,39 @@ function findDevJson(startPath) {
         current = parent;
     }
 }
+/**
+ * Point the build script's `fimo validate` at the exact CLI that scaffolded the
+ * project.
+ *
+ * Inside an npm script a bare `fimo` resolves to whatever is installed in the
+ * project, which is normally the pinned dependency — but only when the install
+ * is current. The hosted build installs the tree itself and then runs this
+ * script, and `validate` is an API client: resolving it from install state
+ * means a project can be checked by a different version than the one it pins,
+ * which is how a project can look clean locally and fail on publish.
+ *
+ * Only an exact npm version is pinned. A source checkout resolves to
+ * `file:<path>`, which is not an npx spec — and there a bare `fimo` already
+ * runs the very binary being developed, which is the point of that flow.
+ */
+export function rewriteFimoValidateCommand(pkg, pin = resolveFimoPin()) {
+    if (!pin || !/^\d+\.\d+\.\d+/.test(pin)) {
+        return false;
+    }
+    const build = pkg.scripts?.build;
+    if (typeof build !== 'string') {
+        return false;
+    }
+    // Only the validate invocation. Anything else the script runs through `fimo`
+    // is local file work, not an API client, and pinning it would add a fetch for
+    // no reason.
+    const pinned = build.replace(/\bfimo validate\b/, `npx fimo@${pin} validate`);
+    if (pinned === build) {
+        return false;
+    }
+    pkg.scripts.build = pinned;
+    return true;
+}
 /**
  * Rewrite `fimo` (in dependencies + devDependencies) to the current pin. Only
  * touches entries that look like a value we own: the template's dist-tag, an old

package/dist/scripts/validate-route-metadata.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pageSourceParamExpressions } from '@fimo/api-contracts';
-import { FIMO_LOCALE_PARAM, resolveRouteContract } from '../runtime/routes/contract.js';
+import { FIMO_LOCALE_PARAM, resolveRouteContract } from '../runtime/routes/index.js';
 import { resolveFimoConfigPath } from '../runtime/shared/fimo-config.server.js';
 import { parseRoutesSource } from './lib/parse-routes-file.js';
 function readJson(filePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"
@@ -118,13 +118,13 @@
   },
   "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-sveltekit.mjs",
+    "build:bundle": "node scripts/bundle-cli.mjs && node scripts/bundle-routes.mjs && node scripts/bundle-sveltekit.mjs",
     "check:types": "tsc -b tsconfig.json && tsc -p tsconfig.test.json",
     "start": "tsx src/cli/index.ts",
     "install-cli": "pnpm build && node scripts/install-cli.mjs",
     "publish-cli": "node scripts/publish-tarball.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",
-    "prepublishOnly": "pnpm run build && pnpm run build:bundle",
+    "prepublishOnly": "pnpm -F @fimo/routes build && pnpm run build && pnpm run build:bundle",
     "release:bump": "node scripts/bump-version.mjs",
     "publish:dry-run": "npm publish --dry-run",
     "postinstall": "node scripts/postinstall.mjs",
@@ -156,6 +156,7 @@
     "@fimo/cli-kit": "workspace:*",
     "@fimo/framework-detect": "workspace:*",
     "@fimo/mcp": "workspace:*",
+    "@fimo/routes": "workspace:*",
     "@fimo/tsconfig": "workspace:*",
     "@modelcontextprotocol/sdk": "1.27.1",
     "@sveltejs/adapter-vercel": "6.3.4",

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.18.0",
+    "fimo": "0.20.0",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

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

@@ -1,116 +0,0 @@
-import type { FimoConfig, FimoRouteConfig } from '../shared/fimo-config.types.js';
-/**
- * The reserved parameter name for the locale segment. A `:locale` placeholder
- * is always the locale, whether or not the route declares a descriptor for it.
- */
-export declare const FIMO_LOCALE_PARAM = "locale";
-export interface FimoEntryParam {
-    type: 'entry';
-    name: string;
-    schema: string;
-    queryField: string;
-    displayField?: string;
-}
-export interface FimoLocaleParam {
-    type: 'locale';
-    name: string;
-    /**
-     * True (the default) means the default locale renders at the unprefixed
-     * path and only other locales carry a `/<locale>` prefix. False means every
-     * locale, the default included, renders behind the prefix.
-     */
-    optional: boolean;
-}
-export type FimoRouteParam = FimoEntryParam | FimoLocaleParam;
-export interface FimoRouteIssue {
-    /** The parameter the issue is about, when it is about one. */
-    param?: string;
-    message: string;
-    /** A concrete edit that resolves the issue. */
-    fix: string;
-}
-export interface FimoRouteContract {
-    id: string;
-    /** The declared route entry, kept so callers can reach `label` / `seo`. */
-    config: FimoRouteConfig;
-    /** The declared path, locale placeholder included (`/:locale/blog/:slug`). */
-    path: string;
-    /** The declared path without the locale placeholder (`/blog/:slug`). */
-    canonicalPath: string;
-    params: FimoRouteParam[];
-    entryParams: FimoEntryParam[];
-    localeParam: FimoLocaleParam | null;
-    /** Placeholders in the path that no usable descriptor resolves. */
-    unresolvedParams: string[];
-    issues: FimoRouteIssue[];
-}
-export interface FimoRouteMatch {
-    contract: FimoRouteContract;
-    /** Every resolved path parameter, the locale segment included. */
-    params: Record<string, string>;
-    /** Entry parameters only — the subset a content lookup may use. */
-    entryParams: Record<string, string>;
-    /** The locale this URL renders. The project default when the path omits it. */
-    locale: string;
-    /** True when the locale came from a path segment rather than the default. */
-    localeFromPath: boolean;
-    /** Static segments matched. Higher wins when several routes match. */
-    score: number;
-}
-/** One URL shape a route produces for one locale. */
-export interface FimoRouteLocaleTarget {
-    locale: string;
-    /** Whether this locale renders behind a `/<locale>` prefix. */
-    prefixed: boolean;
-}
-export declare function normalizeRoutePath(path: string): string;
-/**
- * True when the path declares a locale segment, in either spelling: the config
- * writes `:locale`, a React Router registration writes `:locale?` when the
- * segment may be omitted.
- */
-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`;
- * 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.
- */
-export declare function resolveRouteContract(id: string, route: FimoRouteConfig): FimoRouteContract;
-export declare function resolveRouteContracts(routes: Record<string, FimoRouteConfig> | undefined): FimoRouteContract[];
-/**
- * Match a concrete pathname against the project's routes.
- *
- * The truth table, for a route declared `/:locale/x/:slug` in a project whose
- * default locale is `en`:
- *
- * | URL             | locale param | resolved locale | entry params        |
- * | --------------- | ------------ | --------------- | ------------------- |
- * | `/x/hello`      | optional     | `en` (default)  | `{ slug: 'hello' }` |
- * | `/fr/x/bonjour` | optional     | `fr`            | `{ slug: 'bonjour'}`|
- * | `/en/x/hello`   | optional     | no match        | —                   |
- * | `/x/hello`      | required     | no match        | —                   |
- * | `/en/x/hello`   | required     | `en`            | `{ slug: 'hello' }` |
- *
- * A route with no locale segment always resolves the default locale.
- */
-export declare function matchFimoRoute(pathnameOrUrl: string, config: Pick<FimoConfig, 'routes' | 'i18n'>): FimoRouteMatch | null;
-/**
- * The URL shapes a route produces, one per locale it can render.
- *
- * A route without a locale segment produces a single default-locale URL: under
- * path-prefix routing it has no way to express another locale in its path.
- */
-export declare function routeLocaleTargets(contract: FimoRouteContract, config: Pick<FimoConfig, 'i18n'>): FimoRouteLocaleTarget[];
-/**
- * Build the concrete URL for one locale target. Entry param values are
- * URL-encoded; the locale segment is a prefix, never a substitution, so the
- * canonical default-locale URL carries no locale at all.
- */
-export declare function materializeRoutePath(contract: FimoRouteContract, target: FimoRouteLocaleTarget & {
-    params?: Record<string, string>;
-}): string;
-//# sourceMappingURL=contract.d.ts.map

package/dist/runtime/routes/contract.js

@@ -1,377 +0,0 @@
-// The single source of truth for what a `.fimo/config.json` route means:
-// which of its path placeholders are locales, which are content entries, which
-// URLs it matches, and which URLs it produces. Prefetch, SEO, SSG, sitemap and
-// `fimo validate` all read this module so they cannot drift apart.
-//
-// Browser-safe on purpose: no `node:` imports, no filesystem, no network.
-import { getFimoDefaultLocale, getFimoLocales } from '../i18n/locale.js';
-/**
- * The reserved parameter name for the locale segment. A `:locale` placeholder
- * is always the locale, whether or not the route declares a descriptor for it.
- */
-export const FIMO_LOCALE_PARAM = 'locale';
-export function normalizeRoutePath(path) {
-    const withSlash = path.startsWith('/') ? path : `/${path}`;
-    const collapsed = withSlash.replace(/\/{2,}/g, '/');
-    return collapsed.length > 1 ? collapsed.replace(/\/+$/, '') : collapsed;
-}
-function splitSegments(path) {
-    return path.split('/').filter(Boolean);
-}
-function isPlaceholder(segment) {
-    return segment.startsWith(':') && segment.length > 1;
-}
-function readPlaceholder(segment) {
-    if (!isPlaceholder(segment)) {
-        return null;
-    }
-    return {
-        name: segment.slice(1).replace(/[?*]$/, ''),
-        catchAll: segment.endsWith('*'),
-    };
-}
-/**
- * True when the path declares a locale segment, in either spelling: the config
- * writes `:locale`, a React Router registration writes `:locale?` when the
- * segment may be omitted.
- */
-export function hasLocaleSegment(path) {
-    return splitSegments(normalizeRoutePath(path)).some((segment) => segment === `:${FIMO_LOCALE_PARAM}` || segment === `:${FIMO_LOCALE_PARAM}?`);
-}
-function resolveParamType(name, descriptor) {
-    if (descriptor?.type) {
-        return descriptor.type;
-    }
-    // Omitting `type` keeps every pre-existing route on the entry type; only the
-    // reserved name flips the default.
-    return name === FIMO_LOCALE_PARAM ? 'locale' : 'entry';
-}
-function buildLocaleParam(name, descriptor, index, issues) {
-    if (name !== FIMO_LOCALE_PARAM) {
-        issues.push({
-            param: name,
-            message: `Param "${name}" declares \`"type": "locale"\` but "${FIMO_LOCALE_PARAM}" is the only locale parameter name.`,
-            fix: `Rename the path segment and the descriptor to ":${FIMO_LOCALE_PARAM}", or use \`"type": "entry"\`.`,
-        });
-        return null;
-    }
-    if (index !== 0) {
-        issues.push({
-            param: name,
-            message: `The ":${FIMO_LOCALE_PARAM}" segment must be the first segment of the path.`,
-            fix: `Move it to the front, for example "/:${FIMO_LOCALE_PARAM}/blog/:slug".`,
-        });
-        return null;
-    }
-    for (const field of ['schema', 'queryField', 'displayField', 'query']) {
-        if (descriptor?.[field] !== undefined) {
-            issues.push({
-                param: name,
-                message: `Locale param "${name}" must not declare "${field}" — the locale is read from the URL, never from the CMS.`,
-                fix: `Remove "${field}" from \`params.${name}\`.`,
-            });
-        }
-    }
-    return { type: 'locale', name, optional: descriptor?.optional !== false };
-}
-function buildEntryParam(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": "entry"\`.`,
-            fix: `Drop \`"type": "entry"\` from \`params.${name}\`, or rename the segment.`,
-        });
-        return null;
-    }
-    if (!descriptor) {
-        issues.push({
-            param: name,
-            message: `":${name}" needs \`params\` metadata before its URLs can be generated.`,
-            fix: `Add \`"params": { "${name}": { "schema": "SchemaName", "queryField": "${name}" } }\`.`,
-        });
-        return null;
-    }
-    if (descriptor.optional !== undefined) {
-        issues.push({
-            param: name,
-            message: `Entry param "${name}" cannot be optional — only the locale segment can be omitted from a URL.`,
-            fix: `Remove "optional" from \`params.${name}\`.`,
-        });
-    }
-    if (!descriptor.schema || !descriptor.queryField) {
-        issues.push({
-            param: name,
-            message: `Entry param "${name}" is missing ${!descriptor.schema ? '"schema"' : '"queryField"'}.`,
-            fix: `Set \`"${name}": { "schema": "SchemaName", "queryField": "${name}" }\`.`,
-        });
-        return null;
-    }
-    return {
-        type: 'entry',
-        name,
-        schema: descriptor.schema,
-        queryField: descriptor.queryField,
-        ...(descriptor.displayField ? { displayField: descriptor.displayField } : {}),
-    };
-}
-/**
- * Normalize one declared route into the contract every consumer reads.
- *
- * Parameter types resolve in this order:
- * 1. an explicit `type`;
- * 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.
- */
-export function resolveRouteContract(id, route) {
-    const path = normalizeRoutePath(route.path ?? '/');
-    const segments = splitSegments(path);
-    const declared = route.params ?? {};
-    const issues = [];
-    const params = [];
-    const unresolvedParams = [];
-    const seen = new Set();
-    segments.forEach((segment, index) => {
-        if (!isPlaceholder(segment)) {
-            return;
-        }
-        const placeholder = readPlaceholder(segment);
-        if (!placeholder) {
-            return;
-        }
-        const { name } = placeholder;
-        if (seen.has(name)) {
-            issues.push({
-                param: name,
-                message: `Placeholder ":${name}" appears more than once.`,
-                fix: 'Give each placeholder a distinct name.',
-            });
-            unresolvedParams.push(name);
-            return;
-        }
-        seen.add(name);
-        const descriptor = declared[name];
-        const resolved = resolveParamType(name, descriptor) === 'locale'
-            ? buildLocaleParam(name, descriptor, index, issues)
-            : buildEntryParam(name, descriptor, issues);
-        if (resolved) {
-            params.push(resolved);
-        }
-        else {
-            unresolvedParams.push(name);
-        }
-    });
-    for (const name of Object.keys(declared)) {
-        if (!seen.has(name)) {
-            issues.push({
-                param: name,
-                message: `Declared param "${name}" has no ":${name}" segment in the path.`,
-                fix: `Add ":${name}" to the path, or remove it from "params".`,
-            });
-        }
-    }
-    const localeParam = params.find((param) => param.type === 'locale') ?? null;
-    const canonicalPath = localeParam
-        ? normalizeRoutePath(`/${segments.filter((segment) => segment !== `:${FIMO_LOCALE_PARAM}`).join('/')}`)
-        : path;
-    return {
-        id,
-        config: route,
-        path,
-        canonicalPath,
-        params,
-        entryParams: params.filter((param) => param.type === 'entry'),
-        localeParam,
-        unresolvedParams,
-        issues,
-    };
-}
-export function resolveRouteContracts(routes) {
-    return Object.entries(routes ?? {}).map(([id, route]) => resolveRouteContract(id, route));
-}
-function readLocaleVocabulary(config) {
-    return {
-        locales: config.i18n ? getFimoLocales(config) : null,
-        defaultLocale: getFimoDefaultLocale(config),
-    };
-}
-/**
- * Whether `segment` may stand in the locale slot of this route.
- *
- * An optional locale rejects the default locale: `/hello` is the canonical
- * default-locale URL, so `/en/hello` is a different URL that this route does
- * not serve rather than an alias of it.
- */
-function acceptsLocaleSegment(segment, localeParam, vocabulary) {
-    if (!vocabulary.locales) {
-        return segment.length > 0;
-    }
-    if (!vocabulary.locales.includes(segment)) {
-        return false;
-    }
-    return localeParam.optional ? segment !== vocabulary.defaultLocale : true;
-}
-function matchContract(urlSegments, contract, vocabulary) {
-    const patternSegments = splitSegments(contract.path);
-    const localeParam = contract.localeParam;
-    const catchAllIndex = patternSegments.findIndex((segment) => readPlaceholder(segment)?.catchAll);
-    const hasCatchAll = catchAllIndex !== -1;
-    const hasLocaleLength = hasCatchAll
-        ? urlSegments.length >= patternSegments.length
-        : urlSegments.length === patternSegments.length;
-    const withLocale = localeParam?.optional
-        ? hasLocaleLength && acceptsLocaleSegment(urlSegments[0] ?? '', localeParam, vocabulary)
-        : hasLocaleLength;
-    const withoutLocale = Boolean(localeParam?.optional) &&
-        (hasCatchAll
-            ? urlSegments.length >= patternSegments.length - 1
-            : urlSegments.length === patternSegments.length - 1);
-    if (!localeParam && !withLocale) {
-        return null;
-    }
-    if (localeParam && !withLocale && !withoutLocale) {
-        return null;
-    }
-    const params = {};
-    const entryParams = {};
-    let localeFromPath = null;
-    let score = 0;
-    let offset = 0;
-    for (const [index, patternSegment] of patternSegments.entries()) {
-        if (localeParam && patternSegment === `:${FIMO_LOCALE_PARAM}`) {
-            if (!withLocale) {
-                // The optional locale is absent: every later segment shifts left.
-                offset = -1;
-                continue;
-            }
-            const value = urlSegments[index];
-            if (!acceptsLocaleSegment(value, localeParam, vocabulary)) {
-                return null;
-            }
-            localeFromPath = value;
-            params[FIMO_LOCALE_PARAM] = value;
-            continue;
-        }
-        const value = urlSegments[index + offset];
-        if (value === undefined) {
-            return null;
-        }
-        const placeholder = readPlaceholder(patternSegment);
-        if (placeholder) {
-            const { name, catchAll } = placeholder;
-            const rawValue = catchAll ? urlSegments.slice(index + offset).join('/') : value;
-            const decoded = safeDecode(rawValue);
-            params[name] = decoded;
-            entryParams[name] = decoded;
-            if (catchAll) {
-                break;
-            }
-            continue;
-        }
-        if (patternSegment !== value) {
-            return null;
-        }
-        score += 1;
-    }
-    return {
-        contract,
-        params,
-        entryParams,
-        locale: localeFromPath ?? vocabulary.defaultLocale,
-        localeFromPath: localeFromPath !== null,
-        score,
-    };
-}
-/** Callers pass a pathname or a whole request URL; both must reduce to a path. */
-function readPathname(input) {
-    try {
-        return new URL(input, 'http://fimo.invalid').pathname;
-    }
-    catch {
-        return input.split('#')[0].split('?')[0] || '/';
-    }
-}
-function safeDecode(value) {
-    try {
-        return decodeURIComponent(value);
-    }
-    catch {
-        return value;
-    }
-}
-/**
- * Match a concrete pathname against the project's routes.
- *
- * The truth table, for a route declared `/:locale/x/:slug` in a project whose
- * default locale is `en`:
- *
- * | URL             | locale param | resolved locale | entry params        |
- * | --------------- | ------------ | --------------- | ------------------- |
- * | `/x/hello`      | optional     | `en` (default)  | `{ slug: 'hello' }` |
- * | `/fr/x/bonjour` | optional     | `fr`            | `{ slug: 'bonjour'}`|
- * | `/en/x/hello`   | optional     | no match        | —                   |
- * | `/x/hello`      | required     | no match        | —                   |
- * | `/en/x/hello`   | required     | `en`            | `{ slug: 'hello' }` |
- *
- * A route with no locale segment always resolves the default locale.
- */
-export function matchFimoRoute(pathnameOrUrl, config) {
-    const urlSegments = splitSegments(normalizeRoutePath(readPathname(pathnameOrUrl)));
-    const vocabulary = readLocaleVocabulary(config);
-    let best = null;
-    for (const contract of resolveRouteContracts(config.routes)) {
-        // A route entry without a declared path describes no URL — matching it
-        // against the normalized `/` default would hijack the index route.
-        if (!contract.config.path) {
-            continue;
-        }
-        const match = matchContract(urlSegments, contract, vocabulary);
-        if (match && (!best || match.score > best.score)) {
-            best = match;
-        }
-    }
-    return best;
-}
-/**
- * The URL shapes a route produces, one per locale it can render.
- *
- * A route without a locale segment produces a single default-locale URL: under
- * path-prefix routing it has no way to express another locale in its path.
- */
-export function routeLocaleTargets(contract, config) {
-    const defaultLocale = getFimoDefaultLocale(config);
-    if (!contract.localeParam) {
-        return [{ locale: defaultLocale, prefixed: false }];
-    }
-    const optional = contract.localeParam.optional;
-    return getFimoLocales(config).map((locale) => ({
-        locale,
-        prefixed: optional ? locale !== defaultLocale : true,
-    }));
-}
-/**
- * Build the concrete URL for one locale target. Entry param values are
- * URL-encoded; the locale segment is a prefix, never a substitution, so the
- * canonical default-locale URL carries no locale at all.
- */
-export function materializeRoutePath(contract, target) {
-    const params = target.params ?? {};
-    const substituted = splitSegments(contract.canonicalPath).map((segment) => {
-        const placeholder = readPlaceholder(segment);
-        if (!placeholder) {
-            return segment;
-        }
-        const value = params[placeholder.name];
-        if (value === undefined) {
-            return segment;
-        }
-        return placeholder.catchAll
-            ? value
-                .split('/')
-                .map((part) => encodeURIComponent(part))
-                .join('/')
-            : encodeURIComponent(value);
-    });
-    const prefix = target.prefixed ? [target.locale] : [];
-    return normalizeRoutePath(`/${[...prefix, ...substituted].join('/')}`);
-}