fimo 2.1.0 → 2.2.0-staging.1

package/dist/runtime/astro/server-runtime.js

@@ -8,9 +8,13 @@ export const astroServerContentRuntime = {
     },
     headers(extra) {
         const headers = { ...extra };
-        const env = import.meta.env.FIMO_ENV?.trim();
-        if (env) {
-            headers['X-Fimo-Env'] = env;
+        // `FIMO_ENV` is the variable name a customer's deployed build reads and
+        // keeps its spelling; only the header this build emits is canonical
+        // (branch-cutover ledger, F5). Builds already in production keep sending
+        // `X-Fimo-Env`, which the API still accepts.
+        const branch = import.meta.env.FIMO_ENV?.trim();
+        if (branch) {
+            headers['X-Fimo-Branch'] = branch;
         }
         return headers;
     },

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

@@ -46,9 +46,13 @@ async function fetchEntries(baseUrl, schema, rootDir, locale) {
         url.searchParams.set('limit', '1');
     }
     const headers = {};
-    const env = readEnvValue(rootDir, 'FIMO_ENV') ?? resolveLocalRuntimeEnv({ cwd: rootDir })?.env;
-    if (env) {
-        headers['X-Fimo-Env'] = env;
+    // `FIMO_ENV` is a customer-facing variable name and keeps its spelling; the
+    // header this build emits is canonical (branch-cutover ledger, F5). A
+    // deployed site always talks to the current API, and builds produced by an
+    // older `fimo` keep sending `X-Fimo-Env`, which the API still accepts.
+    const branch = readEnvValue(rootDir, 'FIMO_ENV') ?? resolveLocalRuntimeEnv({ cwd: rootDir })?.env;
+    if (branch) {
+        headers['X-Fimo-Branch'] = branch;
     }
     for (let attempt = 1; attempt <= MAX_FETCH_ATTEMPTS; attempt += 1) {
         const res = await fetch(url, { headers });

package/dist/runtime/shared/branch-identity.d.ts

@@ -0,0 +1,56 @@
+/**
+ * How a local checkout names and addresses a Fimo Branch — runtime-safe copy.
+ *
+ * TRAP: this looks like a duplicate of `@fimo/api-contracts` and it is, on
+ * purpose. `dist/runtime/` and `dist/build/` ship UNBUNDLED inside the `fimo`
+ * npm package and can only import published dependencies; `@fimo/api-contracts`
+ * is a private workspace package, so a runtime import of it breaks every user
+ * project (`ERR_MODULE_NOT_FOUND` from `vite.config.ts`). The CLI binary is
+ * bundled and may import contracts freely — the runtime may not.
+ *
+ * The two copies must agree byte-for-byte or a checkout computes a different
+ * tenant host than the API hands out. `branch-identity.test.ts` pins them
+ * together against a corpus; change one, and that test tells you to change the
+ * other.
+ */
+export declare const DEFAULT_BRANCH = "main";
+export declare const PROD_BRANCH_PREFIX = "release/";
+/** Mirror of `isValidBranch` in `@fimo/api-contracts`. */
+export declare function isValidBranch(branch: string): boolean;
+/**
+ * Mirror of `envResourceKey` in `@fimo/api-contracts`. Keeps that name on both
+ * sides: its OUTPUT is a live tenant hostname and R2 prefix, and the symbol
+ * rename is a later slice (branch-cutover ledger, F10).
+ */
+export declare function envResourceKey(branch: string): string;
+/** Mirror of `buildTenantApiUrl` in `@fimo/api-contracts`. */
+export declare function buildTenantApiUrl(projectId: string, branch: string, tenantApiBaseUrl: string): string;
+/**
+ * Content-API aliases a local checkout exposes — one per framework family
+ * that has a Fimo startup hook (Vite/React Router, Next, Astro, SvelteKit).
+ * Add a key when its framework's hook lands, not before: an alias no runtime
+ * reads is one more line to reason about when a site talks to the wrong Branch.
+ *
+ * These are process-env variable names in a CUSTOMER's app; they keep their
+ * `ENV` spelling (branch-cutover ledger, F3 "Preserve").
+ */
+export declare const LOCAL_CONTENT_API_ENV_KEYS: readonly ['FIMO_CONTENT_API_URL', 'VITE_API_URL', 'NEXT_PUBLIC_FIMO_API_URL', 'PUBLIC_FIMO_API_URL'];
+/**
+ * Branch selectors a runtime turns into the Branch request header.
+ *
+ * `FIMO_ENV` / `NEXT_PUBLIC_FIMO_ENV` are the variable names a customer's
+ * deployed build reads; renaming either breaks it (branch-cutover ledger,
+ * "Names that must not be mechanically renamed").
+ */
+export declare const LOCAL_ENV_SELECTOR_KEYS: readonly ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
+/**
+ * Both halves move together. The tenant URL selects the Branch for content
+ * reads (each Branch has its own host); the selectors select it for every
+ * service that reads the Branch header. Setting one without the other points a
+ * checkout at two different Branches.
+ */
+export declare function buildLocalRuntimeEnv(options: {
+    readonly tenantApiUrl: string;
+    readonly branch: string;
+}): Record<string, string>;
+//# sourceMappingURL=branch-identity.d.ts.map

package/dist/runtime/shared/{env-identity.js → branch-identity.js}

@@ -1,5 +1,5 @@
 /**
- * How a local checkout names and addresses a Fimo env — runtime-safe copy.
+ * How a local checkout names and addresses a Fimo Branch — runtime-safe copy.
  *
  * TRAP: this looks like a duplicate of `@fimo/api-contracts` and it is, on
  * purpose. `dist/runtime/` and `dist/build/` ship UNBUNDLED inside the `fimo`
@@ -9,32 +9,32 @@
  * bundled and may import contracts freely — the runtime may not.
  *
  * The two copies must agree byte-for-byte or a checkout computes a different
- * tenant host than the API hands out. `env-identity.test.ts` pins them
+ * tenant host than the API hands out. `branch-identity.test.ts` pins them
  * together against a corpus; change one, and that test tells you to change the
  * other.
  */
-export const DEFAULT_ENV = 'main';
-export const PROD_ENV_PREFIX = 'release/';
-const ENV_ID_REGEX = /^[a-zA-Z0-9._/-]+$/;
-const MAX_ENV_LENGTH = 255;
-/** Mirror of `isValidEnv` in `@fimo/api-contracts`. */
-export function isValidEnv(env) {
-    if (typeof env !== 'string') {
+export const DEFAULT_BRANCH = 'main';
+export const PROD_BRANCH_PREFIX = 'release/';
+const BRANCH_ID_REGEX = /^[a-zA-Z0-9._/-]+$/;
+const MAX_BRANCH_LENGTH = 255;
+/** Mirror of `isValidBranch` in `@fimo/api-contracts`. */
+export function isValidBranch(branch) {
+    if (typeof branch !== 'string') {
         return false;
     }
-    if (env.length === 0 || env.length > MAX_ENV_LENGTH) {
+    if (branch.length === 0 || branch.length > MAX_BRANCH_LENGTH) {
         return false;
     }
-    if (env.startsWith('-') || env.startsWith('.')) {
+    if (branch.startsWith('-') || branch.startsWith('.')) {
         return false;
     }
-    if (env.includes('//') || env.includes('--')) {
+    if (branch.includes('//') || branch.includes('--')) {
         return false;
     }
-    if (env.split('/').some((segment) => segment === '..')) {
+    if (branch.split('/').some((segment) => segment === '..')) {
         return false;
     }
-    return ENV_ID_REGEX.test(env);
+    return BRANCH_ID_REGEX.test(branch);
 }
 function fnv1a8(s) {
     let h = 0x811c9dc5;
@@ -44,27 +44,34 @@ function fnv1a8(s) {
     }
     return (h >>> 0).toString(16).padStart(8, '0');
 }
-/** Mirror of `envResourceKey` in `@fimo/api-contracts`. */
-export function envResourceKey(env) {
-    const base = env
+/**
+ * Mirror of `envResourceKey` in `@fimo/api-contracts`. Keeps that name on both
+ * sides: its OUTPUT is a live tenant hostname and R2 prefix, and the symbol
+ * rename is a later slice (branch-cutover ledger, F10).
+ */
+export function envResourceKey(branch) {
+    const base = branch
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '')
         .slice(0, 15);
-    const hash = fnv1a8(env);
+    const hash = fnv1a8(branch);
     return base ? `${base}-${hash}` : hash;
 }
 /** Mirror of `buildTenantApiUrl` in `@fimo/api-contracts`. */
-export function buildTenantApiUrl(projectId, env, tenantApiBaseUrl) {
+export function buildTenantApiUrl(projectId, branch, tenantApiBaseUrl) {
     const url = new URL(tenantApiBaseUrl);
-    url.hostname = `${projectId}-${envResourceKey(env)}.${url.hostname}`;
+    url.hostname = `${projectId}-${envResourceKey(branch)}.${url.hostname}`;
     return url.toString().replace(/\/$/, '');
 }
 /**
  * Content-API aliases a local checkout exposes — one per framework family
  * that has a Fimo startup hook (Vite/React Router, Next, Astro, SvelteKit).
  * Add a key when its framework's hook lands, not before: an alias no runtime
- * reads is one more line to reason about when a site talks to the wrong env.
+ * reads is one more line to reason about when a site talks to the wrong Branch.
+ *
+ * These are process-env variable names in a CUSTOMER's app; they keep their
+ * `ENV` spelling (branch-cutover ledger, F3 "Preserve").
  */
 export const LOCAL_CONTENT_API_ENV_KEYS = [
     'FIMO_CONTENT_API_URL',
@@ -72,17 +79,23 @@ export const LOCAL_CONTENT_API_ENV_KEYS = [
     'NEXT_PUBLIC_FIMO_API_URL',
     'PUBLIC_FIMO_API_URL',
 ];
-/** Env selectors a runtime turns into the `X-Fimo-Env` request header. */
+/**
+ * Branch selectors a runtime turns into the Branch request header.
+ *
+ * `FIMO_ENV` / `NEXT_PUBLIC_FIMO_ENV` are the variable names a customer's
+ * deployed build reads; renaming either breaks it (branch-cutover ledger,
+ * "Names that must not be mechanically renamed").
+ */
 export const LOCAL_ENV_SELECTOR_KEYS = ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
 /**
- * Both halves move together. The tenant URL selects the env for content reads
- * (each env has its own host); the selectors select it for every service that
- * reads `X-Fimo-Env`. Setting one without the other points a checkout at two
- * different envs.
+ * Both halves move together. The tenant URL selects the Branch for content
+ * reads (each Branch has its own host); the selectors select it for every
+ * service that reads the Branch header. Setting one without the other points a
+ * checkout at two different Branches.
  */
 export function buildLocalRuntimeEnv(options) {
     return {
         ...Object.fromEntries(LOCAL_CONTENT_API_ENV_KEYS.map((key) => [key, options.tenantApiUrl])),
-        ...Object.fromEntries(LOCAL_ENV_SELECTOR_KEYS.map((key) => [key, options.env])),
+        ...Object.fromEntries(LOCAL_ENV_SELECTOR_KEYS.map((key) => [key, options.branch])),
     };
 }

package/dist/runtime/shared/local-runtime-env.d.ts

@@ -38,9 +38,9 @@ export declare function resolveLocalRuntimeEnv(options: {
     readonly cwd: string;
 }): LocalRuntimeEnv | null;
 /**
- * The one case where "explicit wins" pins the app to the WRONG env: an
+ * The one case where "explicit wins" pins the app to the WRONG Branch: an
  * explicit tenant URL that Fimo itself minted for this project (old-CLI
- * `fimo clone` seeded the clone-time env's URL into `.env`) and that disagrees
+ * `fimo clone` seeded the clone-time Branch's URL into `.env`) and that disagrees
  * with the branch. A URL the user typed — `http://localhost:4000` — is never
  * reported; that is the override the design exists to protect.
  */

package/dist/runtime/shared/local-runtime-env.js

@@ -19,7 +19,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { CURRENT_PROJECT_LAYOUT, LEGACY_PROJECT_LAYOUT } from '../project-layout.js';
-import { DEFAULT_ENV, LOCAL_CONTENT_API_ENV_KEYS, buildLocalRuntimeEnv, buildTenantApiUrl, isValidEnv, } from './env-identity.js';
+import { DEFAULT_BRANCH, LOCAL_CONTENT_API_ENV_KEYS, buildLocalRuntimeEnv, buildTenantApiUrl, isValidBranch, } from './branch-identity.js';
 /**
  * Derive the local runtime env, or `null` when this directory is not a linked
  * Fimo project (or the link predates `tenantApiBaseUrl` — nothing safe to
@@ -31,21 +31,23 @@ export function resolveLocalRuntimeEnv(options) {
     if (!root || !link) {
         return null;
     }
-    const branch = currentBranch(root);
-    const env = branch ?? DEFAULT_ENV;
-    const tenantApiUrl = buildTenantApiUrl(link.projectId, env, link.tenantApiBaseUrl);
+    const gitBranch = currentBranch(root);
+    const branch = gitBranch ?? DEFAULT_BRANCH;
+    const tenantApiUrl = buildTenantApiUrl(link.projectId, branch, link.tenantApiBaseUrl);
     return {
-        env,
+        // `env` stays the field name: `resolveLocalRuntimeEnv` is a published
+        // `fimo/config` export that framework adapters destructure.
+        env: branch,
         tenantApiUrl,
-        source: branch ? 'branch' : 'fallback',
-        values: buildLocalRuntimeEnv({ tenantApiUrl, env }),
+        source: gitBranch ? 'branch' : 'fallback',
+        values: buildLocalRuntimeEnv({ tenantApiUrl, branch }),
         link,
     };
 }
 /**
- * The one case where "explicit wins" pins the app to the WRONG env: an
+ * The one case where "explicit wins" pins the app to the WRONG Branch: an
  * explicit tenant URL that Fimo itself minted for this project (old-CLI
- * `fimo clone` seeded the clone-time env's URL into `.env`) and that disagrees
+ * `fimo clone` seeded the clone-time Branch's URL into `.env`) and that disagrees
  * with the branch. A URL the user typed — `http://localhost:4000` — is never
  * reported; that is the override the design exists to protect.
  */
@@ -128,7 +130,7 @@ function currentBranch(root) {
             stdio: ['ignore', 'pipe', 'ignore'],
             encoding: 'utf-8',
         }).trim();
-        return branch && branch !== 'HEAD' && isValidEnv(branch) ? branch : null;
+        return branch && branch !== 'HEAD' && isValidBranch(branch) ? branch : null;
     }
     catch {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "2.1.0",
+  "version": "2.2.0-staging.1",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "keywords": [
     "astro-component"
@@ -184,12 +184,12 @@
   "devDependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
-    "@fimo/agents-bundle": "2.1.0",
-    "@fimo/api-contracts": "2.1.0",
-    "@fimo/cli-kit": "2.1.0",
-    "@fimo/framework-detect": "2.1.0",
-    "@fimo/routes": "2.1.0",
-    "@fimo/tsconfig": "2.1.0",
+    "@fimo/agents-bundle": "2.2.0-staging.1",
+    "@fimo/api-contracts": "2.2.0-staging.1",
+    "@fimo/cli-kit": "2.2.0-staging.1",
+    "@fimo/framework-detect": "2.2.0-staging.1",
+    "@fimo/routes": "2.2.0-staging.1",
+    "@fimo/tsconfig": "2.2.0-staging.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.1.0",
-    "fimo-astro": "2.1.0"
+    "fimo": "2.2.0-staging.1",
+    "fimo-astro": "2.2.0-staging.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.1.0",
-    "fimo-next": "2.1.0",
-    "fimo-react": "2.1.0",
+    "fimo": "2.2.0-staging.1",
+    "fimo-next": "2.2.0-staging.1",
+    "fimo-react": "2.2.0-staging.1",
     "next": "^16.3.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"

package/templates/react-router/package.json

@@ -21,10 +21,10 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "2.1.0",
-    "fimo-react": "2.1.0",
-    "fimo-react-router": "2.1.0",
-    "fimo-vite": "2.1.0",
+    "fimo": "2.2.0-staging.1",
+    "fimo-react": "2.2.0-staging.1",
+    "fimo-react-router": "2.2.0-staging.1",
+    "fimo-vite": "2.2.0-staging.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.1.0",
-    "fimo-sveltekit": "2.1.0"
+    "fimo": "2.2.0-staging.1",
+    "fimo-sveltekit": "2.2.0-staging.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.1.0",
-    "fimo-react": "2.1.0",
-    "fimo-react-router": "2.1.0",
-    "fimo-vite": "2.1.0",
+    "fimo": "2.2.0-staging.1",
+    "fimo-react": "2.2.0-staging.1",
+    "fimo-react-router": "2.2.0-staging.1",
+    "fimo-vite": "2.2.0-staging.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-router": "^8.3.0"

package/dist/runtime/shared/env-identity.d.ts

@@ -1,43 +0,0 @@
-/**
- * How a local checkout names and addresses a Fimo env — runtime-safe copy.
- *
- * TRAP: this looks like a duplicate of `@fimo/api-contracts` and it is, on
- * purpose. `dist/runtime/` and `dist/build/` ship UNBUNDLED inside the `fimo`
- * npm package and can only import published dependencies; `@fimo/api-contracts`
- * is a private workspace package, so a runtime import of it breaks every user
- * project (`ERR_MODULE_NOT_FOUND` from `vite.config.ts`). The CLI binary is
- * bundled and may import contracts freely — the runtime may not.
- *
- * The two copies must agree byte-for-byte or a checkout computes a different
- * tenant host than the API hands out. `env-identity.test.ts` pins them
- * together against a corpus; change one, and that test tells you to change the
- * other.
- */
-export declare const DEFAULT_ENV = "main";
-export declare const PROD_ENV_PREFIX = "release/";
-/** Mirror of `isValidEnv` in `@fimo/api-contracts`. */
-export declare function isValidEnv(env: string): boolean;
-/** Mirror of `envResourceKey` in `@fimo/api-contracts`. */
-export declare function envResourceKey(env: string): string;
-/** Mirror of `buildTenantApiUrl` in `@fimo/api-contracts`. */
-export declare function buildTenantApiUrl(projectId: string, env: string, tenantApiBaseUrl: string): string;
-/**
- * Content-API aliases a local checkout exposes — one per framework family
- * that has a Fimo startup hook (Vite/React Router, Next, Astro, SvelteKit).
- * Add a key when its framework's hook lands, not before: an alias no runtime
- * reads is one more line to reason about when a site talks to the wrong env.
- */
-export declare const LOCAL_CONTENT_API_ENV_KEYS: readonly ['FIMO_CONTENT_API_URL', 'VITE_API_URL', 'NEXT_PUBLIC_FIMO_API_URL', 'PUBLIC_FIMO_API_URL'];
-/** Env selectors a runtime turns into the `X-Fimo-Env` request header. */
-export declare const LOCAL_ENV_SELECTOR_KEYS: readonly ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
-/**
- * Both halves move together. The tenant URL selects the env for content reads
- * (each env has its own host); the selectors select it for every service that
- * reads `X-Fimo-Env`. Setting one without the other points a checkout at two
- * different envs.
- */
-export declare function buildLocalRuntimeEnv(options: {
-    readonly tenantApiUrl: string;
-    readonly env: string;
-}): Record<string, string>;
-//# sourceMappingURL=env-identity.d.ts.map