fimo 0.17.0 → 0.19.0

package/assets/skills/fimo-migration/scripts/write-migration-report.mjs

@@ -11,17 +11,19 @@ function main() {
   const manifest = readJson(manifestPath);
 
   const checks = buildChecks(manifest, projectRoot);
+  const dimensions = buildDimensions(manifest);
   const status = determineStatus(checks, manifest);
   const updatedManifest = {
     ...manifest,
     qa: {
       status,
       checks,
+      dimensions,
       reportPath: toPosix(path.relative(projectRoot, reportPath)),
       updatedAt: new Date().toISOString(),
     },
   };
-  const report = buildReport(updatedManifest, checks);
+  const report = buildReport(updatedManifest, checks, dimensions, readTimings(projectRoot));
 
   fs.mkdirSync(path.dirname(reportPath), { recursive: true });
   fs.writeFileSync(reportPath, report, 'utf8');
@@ -167,7 +169,169 @@ function determineStatus(checks, manifest) {
   return 'passed-with-unresolved';
 }
 
-function buildReport(manifest, checks) {
+// Each migration surface is reported on its own row. There is deliberately no
+// aggregate score: a perfect route coverage must never average away missing
+// entries or an unuploaded asset.
+const DIMENSIONS = [
+  { id: 'routes', gate: 'blocking', items: (manifest) => manifest.routes },
+  { id: 'content-types', gate: 'blocking', items: (manifest) => manifest.contentTypes },
+  { id: 'entries', gate: 'blocking', items: (manifest) => manifest.entries },
+  { id: 'media', gate: 'blocking', items: (manifest) => manifest.media },
+  { id: 'forms', gate: 'blocking', items: (manifest) => manifest.forms },
+  { id: 'labels', gate: 'advisory', items: (manifest) => manifest.labels },
+  { id: 'locales', gate: 'advisory', items: (manifest) => manifest.locales },
+  { id: 'redirects', gate: 'advisory', items: (manifest) => manifest.redirects },
+  { id: 'seo', gate: 'advisory', items: (manifest) => manifest.seo },
+];
+
+const UNRESOLVED_DIMENSION_AREAS = {
+  routes: ['route', 'routes'],
+  'content-types': ['content-type', 'schema'],
+  entries: ['content', 'entry'],
+  media: ['asset', 'media'],
+  forms: ['form', 'forms'],
+  labels: ['label', 'labels'],
+  locales: ['locale', 'locales'],
+  redirects: ['redirect', 'redirects'],
+  seo: ['seo'],
+};
+
+const MIGRATED_STATUSES = ['imported', 'verified'];
+
+function buildDimensions(manifest) {
+  return DIMENSIONS.map((dimension) => {
+    const items = asArray(dimension.items(manifest));
+    const unresolved = unresolvedForDimension(manifest, dimension.id, items);
+    const withStatus = (status) => items.filter((item) => item.status === status).length;
+    const discovered = items.length + unresolved.length;
+    const migrated = items.filter((item) => MIGRATED_STATUSES.includes(item.status)).length;
+    const unresolvedCount = withStatus('unresolved') + unresolved.length;
+    const unsupported = withStatus('unsupported');
+    // Deliberate drops are out of scope, so they do not count against coverage.
+    const denominator = discovered - withStatus('ignored');
+    const accounted = migrated + unresolvedCount + unsupported;
+    return {
+      dimension: dimension.id,
+      gate: dimension.gate,
+      discovered,
+      migrated,
+      verified: withStatus('verified'),
+      unresolved: unresolvedCount,
+      unsupported,
+      denominator,
+      coverage: denominator === 0 ? null : Math.round((accounted / denominator) * 1000) / 1000,
+    };
+  });
+}
+
+function unresolvedForDimension(manifest, dimensionId, items) {
+  const areas = UNRESOLVED_DIMENSION_AREAS[dimensionId] ?? [];
+  const itemIds = new Set(items.map((item) => item.id).filter(isNonEmptyString));
+  return asArray(manifest.unresolved).filter(
+    (item) => areas.includes(item.area) && (!isNonEmptyString(item.id) || !itemIds.has(item.id))
+  );
+}
+
+function dimensionTable(dimensions) {
+  const columns = [
+    'dimension',
+    'gate',
+    'discovered',
+    'migrated',
+    'verified',
+    'unresolved',
+    'unsupported',
+    'denominator',
+    'coverage',
+  ];
+  return [
+    `| ${columns.join(' | ')} |`,
+    `| ${columns.map(() => '---').join(' | ')} |`,
+    ...dimensions.map(
+      (row) => `| ${columns.map((column) => (row[column] === null ? 'n/a' : String(row[column]))).join(' | ')} |`
+    ),
+  ].join('\n');
+}
+
+/**
+ * Durations live in run receipts, never in the manifest, so the canonical
+ * ledger stays byte-stable across identical reruns. The harness timing file is
+ * included when a standalone agent acceptance produced one.
+ */
+function readTimings(projectRoot) {
+  return [...readHarnessTimings(projectRoot), ...readWorkerTimings(projectRoot), ...readApplyTimings(projectRoot)];
+}
+
+function readHarnessTimings(projectRoot) {
+  const timing = readJsonOrNull(path.join(projectRoot, '.fimo/migration/timings.json'));
+  if (!timing || typeof timing !== 'object') {
+    return [];
+  }
+  return [
+    {
+      stage: 'agent',
+      step: timing.model ?? 'claude',
+      durationMs: numberOr(timing.wallTimeMs, 0),
+      status: timing.timedOut ? 'timeout' : 'complete',
+    },
+  ];
+}
+
+function readWorkerTimings(projectRoot) {
+  const workersDir = path.join(projectRoot, '.fimo/migration/workers');
+  if (!fs.existsSync(workersDir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(workersDir)
+    .filter((file) => file.endsWith('.json'))
+    .sort()
+    .flatMap((file) => {
+      const receipt = readJsonOrNull(path.join(workersDir, file));
+      if (!receipt) {
+        return [];
+      }
+      return [
+        {
+          stage: 'worker',
+          step: receipt.id ?? path.basename(file, '.json'),
+          durationMs: numberOr(receipt.durationMs, 0),
+          status: receipt.status ?? 'complete',
+        },
+      ];
+    });
+}
+
+function readApplyTimings(projectRoot) {
+  const run = readJsonOrNull(path.join(projectRoot, '.fimo/migration/apply-run.json'));
+  return asArray(run?.phases).map((item) => ({
+    stage: 'apply',
+    step: item.phase ?? 'unknown',
+    durationMs: numberOr(item.durationMs, 0),
+    status: item.status ?? 'complete',
+  }));
+}
+
+function readJsonOrNull(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function timingSection(timings) {
+  if (timings.length === 0) {
+    return '- No run receipts recorded.';
+  }
+  return [
+    '| stage | step | status | duration_ms |',
+    '| --- | --- | --- | --- |',
+    ...timings.map((item) => `| ${item.stage} | ${item.step} | ${item.status} | ${item.durationMs} |`),
+  ].join('\n');
+}
+
+function buildReport(manifest, checks, dimensions, timings) {
   const statusLabel =
     manifest.qa.status === 'passed'
       ? 'complete'
@@ -188,6 +352,11 @@ function buildReport(manifest, checks) {
     bullet('Platform', manifest.source?.platform),
     bullet('Public URL', manifest.source?.publicUrl),
     bullet('Root path', manifest.source?.rootPath),
+    bullet('CLI', manifest.source?.cli),
+    '',
+    '## Coverage by dimension',
+    '',
+    dimensionTable(dimensions),
     '',
     '## Routes',
     '',
@@ -211,6 +380,11 @@ function buildReport(manifest, checks) {
     `- SEO items: ${asArray(manifest.seo).length}`,
     `- Redirects: ${asArray(manifest.redirects).length}`,
     `- Locales: ${asArray(manifest.locales).length}`,
+    `- Labels: ${asArray(manifest.labels).length}`,
+    '',
+    '## Timing',
+    '',
+    timingSection(timings),
     '',
     '## Checks',
     '',
@@ -335,7 +509,7 @@ function contentCountsPass(manifest) {
 function schemasPushedPass(manifest) {
   const requiredTypes = entryBatchTypesNeedingSchema(manifest);
   if (requiredTypes.size === 0) return true;
-  const byName = new Map(asArray(manifest.contentTypes).map((type) => [type.name ?? type.uid, type]));
+  const byName = contentTypeIndex(manifest);
   for (const name of requiredTypes) {
     const type = byName.get(name);
     if (!type || !['imported', 'verified'].includes(type.status)) return false;
@@ -343,9 +517,22 @@ function schemasPushedPass(manifest) {
   return true;
 }
 
+// An entry batch names its content type by uid (that is what `fimo entries`
+// takes), while a manifest content type also carries a human display name.
+// Index both so neither spelling looks like a missing schema.
+function contentTypeIndex(manifest) {
+  const index = new Map();
+  for (const type of asArray(manifest.contentTypes)) {
+    for (const key of [type.uid, type.name]) {
+      if (isNonEmptyString(key)) index.set(key, type);
+    }
+  }
+  return index;
+}
+
 function schemaPushStats(manifest) {
   const requiredTypes = entryBatchTypesNeedingSchema(manifest);
-  const byName = new Map(asArray(manifest.contentTypes).map((type) => [type.name ?? type.uid, type]));
+  const byName = contentTypeIndex(manifest);
   const pushed = [...requiredTypes].filter((name) => ['imported', 'verified'].includes(byName.get(name)?.status));
   return {
     requiredTypes: requiredTypes.size,

package/assets/skills/fimo-studio/references/ai-chat.md

@@ -22,7 +22,7 @@ Give the AI more to work with:
 - **+ button**: Opens a dropdown with options:
   - **Attach Assets** -- browse your media library and attach files.
   - **Attach Entries** -- attach CMS content for the AI to reference.
-  - **Upload from Computer** -- upload a new file directly.
+  - **Upload from Computer** -- upload a file directly. ZIP archives are supported up to 20 MiB; the AI can download and inspect them under `/tmp` in its sandbox while the original stays attached to the conversation.
   - **Draw** -- opens the drawing tool where you can sketch a wireframe or layout idea for the AI to follow.
 - **@ mentions**: Type **@** in the chat to reference specific files, pages, or content inline.
 

package/assets/skills/fimo-studio/references/cms.md

@@ -1,24 +1,41 @@
 ## How the CMS Works
 
-The CMS is where you manage your site's structured content. It separates content by whether a schema is repeatable:
+The CMS is where you manage your site's structured content:
 
+- **Pages** compose declared Labels, Singles, and Collection queries around the routes where they appear.
 - **Collections** hold multiple entries of the same kind, such as Blog posts, Team members, or Testimonials.
 - **Singles** hold one set of content, such as Site settings, a Homepage, or an About page.
 - **Entries** are the individual records inside a Collection.
 
 Both use schemas to define their fields. The difference is whether you edit one set of content or manage a repeatable list.
 
+Pages is still a pre-release Studio surface. It is visible in development and staging, but hidden in production until the public release. If Pages is absent, use Collections, Singles, and Labels & Text normally.
+
 ## Browsing Your Content
 
 1. Click the **Content tab** (the database icon) in the top navigation bar.
-2. Choose **Collections** or **Singles** in the left sidebar. **Forms** and **Labels & Text** follow them in the same list.
+2. Choose **Pages**, **Collections**, or **Singles** in the left sidebar. **Forms** and **Labels & Text** follow them in the same list.
 3. Hover over or focus the info icon beside any item for a short explanation.
-4. Each destination shows cards for the schemas in that group.
-5. Click a Collection to see its entries, then click an entry to edit it.
-6. Click a Single to edit it directly.
+4. Pages shows the site's route tree. Collections and Singles show cards for the schemas in that group.
+5. Select a page to edit its declared sources together. For a dynamic route, choose the concrete entry from the header selector.
+6. Click a Collection to see its entries, then click an entry to edit it.
+7. Click a Single to edit it directly.
 
 Collection cards show their entry count. Single cards are labeled **Single** instead because they always represent one set of content.
 
+## Editing by Page
+
+1. Open **Content → Pages**.
+2. Select a route from the page tree. The homepage stays first; related routes can be grouped into folders.
+3. Edit its Labels, Singles, bound entry, or Collection-source results in one page-shaped view.
+4. Use **Open in Preview** to switch to the selected route.
+
+Agents declare each route's `params` and `sources`; Studio uses those declarations to build the Pages tree and show the content editors manage for that route.
+
+Label and Single sources use the page as their editing home. Collection sources remain reusable and stay visible in Collections; Pages only shows the entries selected by the declared query. For a dynamic page, selecting a concrete entry resolves any `$params.<param>.<field>` values and refreshes dependent sources.
+
+A route with several parameters, such as `/shop/:category/:product`, is chosen left to right. Studio asks for the category first, then offers only products matching `where: { "category": "$params.category.id" }`. Changing the category clears the product selection so the page cannot keep a product from another category.
+
 ## Editing a Single
 
 1. Open **Content → Singles**.
@@ -53,7 +70,7 @@ Fimo does not send the prompt automatically. After the AI finishes, translated e
 2. Click the **+** (plus) icon button at the top of the Collection (labeled **New entry** on hover). If the Collection is empty, use the **Create entry** button in the center of the empty state instead.
 3. Fill in the form fields (text, images, dates, whatever the collection defines).
 
-Changes save automatically as you fill in each field (the save is debounced), so there is no Save button. The save status appears in the top bar (Saving / Saved). An incomplete new entry waits until its required fields are valid before it becomes part of the Collection. If the Collection is wired to a page on your site, new content shows up automatically.
+Changes save automatically as you fill in each field (the save is debounced), so there is no Save button. The save status appears in the top bar (Saving / Saved). An incomplete new entry waits until its required fields are valid before it becomes part of the Collection. A page source can make matching entries visible from the Pages workspace.
 
 ## Editing an Entry
 
@@ -100,7 +117,8 @@ The AI chat can help you manage content without navigating through menus:
 
 - **Collections** are best for repeatable content. Open one to search, sort, create, and manage its entries.
 - **Singles** are best for one-off content. Open one and edit it directly.
-- **Content appears automatically** if its schema is connected (wired) to a page on your site. You do not need to manually link each entry.
+- **Pages** organize existing labels and entries around the structure of the site.
+- **Page sources organize usage, not entry membership.** A Collection query decides which reusable entries the Pages workspace shows; the entries remain available under Collections.
 - **Forms tab**: View and manage form submissions collected from your site's forms.
 - **Labels & Text tab**: Edit your site's UI labels and static text strings as key-and-value rows. This is for your site's interface copy, not for translated copies of collection entries.
 - **Search and sort**: Use the search bar to filter entries and the sort dropdown to order them quickly.

package/assets/skills/fimo-studio/references/webhooks.md

@@ -1,6 +1,6 @@
 # Webhooks
 
-> **Beta:** Test each destination and review its delivery history before depending on it in production.
+> Test each destination and review its delivery history before depending on it in production.
 
 Webhooks send project activity to an external HTTPS endpoint. Use them for focused reactions such as adding a waitlist submission to an email tool, notifying Slack after a publish, or starting a GitHub workflow after an agent review.
 

package/assets/sveltekit/components/DateTime.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+  import type { HTMLTimeAttributes } from 'svelte/elements';
+
+  import type { FimoString } from 'fimo/sveltekit';
+  import { getFimoSource } from 'fimo/sveltekit';
+
+  type Props = Omit<HTMLTimeAttributes, 'datetime' | 'children'> & {
+    value: FimoString | globalThis.Date | string | number | null | undefined;
+    locale?: string;
+    options?: Intl.DateTimeFormatOptions;
+  };
+
+  let { value, locale, options, ...props }: Props = $props();
+  const source = $derived(getFimoSource(value));
+  const rendered = $derived.by(() => {
+    if (value == null) {
+      return null;
+    }
+    const raw = value instanceof String ? value.toString() : value;
+    const date = new globalThis.Date(raw as string | number | globalThis.Date);
+    if (Number.isNaN(date.getTime())) {
+      return null;
+    }
+    return {
+      // The whole instant, not just the day: a `datetime` field exists to name
+      // a moment, and truncating it here would throw the time away.
+      datetime: date.toISOString(),
+      text: date.toLocaleString(locale, options ?? { dateStyle: 'medium', timeStyle: 'short' }),
+    };
+  });
+</script>
+
+{#if rendered}
+  <time {...props} datetime={rendered.datetime} data-fimo-source={source}>{rendered.text}</time>
+{/if}

package/assets/sveltekit/components/FimoProvider.svelte

@@ -22,12 +22,12 @@
       return;
     }
 
-    return connectPreview({ goto, invalidateAll });
+    return connectPreview({ goto, invalidateAll, locale: () => labels.locale });
   });
 
   afterNavigate(() => {
     if (previewEnabled) {
-      sendPreviewLocation();
+      sendPreviewLocation(labels.locale);
     }
   });
 </script>

package/assets/sveltekit/components/index.d.ts

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.svelte';
 export { default as Date } from './Date.svelte';
+export { default as DateTime } from './DateTime.svelte';
 export { default as FimoProvider } from './FimoProvider.svelte';
 export { default as Image } from './Image.svelte';
 export { default as Json } from './Json.svelte';

package/assets/sveltekit/components/index.js

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.svelte';
 export { default as Date } from './Date.svelte';
+export { default as DateTime } from './DateTime.svelte';
 export { default as FimoProvider } from './FimoProvider.svelte';
 export { default as Image } from './Image.svelte';
 export { default as Json } from './Json.svelte';

package/dist/build/next/config.d.ts

@@ -5,8 +5,11 @@ export interface FimoNextConfigContext {
 export type FimoNextConfigFactory<TConfig extends object = object> = (phase: string, context: FimoNextConfigContext) => TConfig | Promise<TConfig>;
 export type FimoNextConfig<TConfig extends object = object> = TConfig | FimoNextConfigFactory<TConfig>;
 /**
- * Connect a Next development server to Fimo's hosted preview gateway.
+ * Wire a Next application to its linked Fimo project.
  *
+ * Fills the Fimo runtime env from the local link in `next dev`, `next build`,
+ * and `next start` — per key, only when nothing else set it — and, in
+ * development only, connects the dev server to Fimo's hosted preview gateway.
  * The platform supplies allowed preview origins at runtime, so applications do
  * not need to know which preview provider Fimo currently uses.
  */

package/dist/build/next/config.js

@@ -1,5 +1,13 @@
 import { findStaleFimoOverride, resolveLocalRuntimeEnv, staleOverrideMessage, } from '../../runtime/shared/local-runtime-env.js';
 const NEXT_DEVELOPMENT_PHASE = 'phase-development-server';
+// The content runtime reads process.env only, so every phase that runs
+// application code needs the derived env: the dev server, the production build
+// (prerendering + NEXT_PUBLIC_* inlining), and the production server.
+const RUNTIME_ENV_PHASES = new Set([
+    NEXT_DEVELOPMENT_PHASE,
+    'phase-production-build',
+    'phase-production-server',
+]);
 const PREVIEW_ORIGINS_ENV = 'FIMO_PREVIEW_ALLOWED_ORIGINS';
 function readPreviewOrigins() {
     return (process.env[PREVIEW_ORIGINS_ENV] ?? '')
@@ -8,8 +16,11 @@ function readPreviewOrigins() {
         .filter(Boolean);
 }
 /**
- * Connect a Next development server to Fimo's hosted preview gateway.
+ * Wire a Next application to its linked Fimo project.
  *
+ * Fills the Fimo runtime env from the local link in `next dev`, `next build`,
+ * and `next start` — per key, only when nothing else set it — and, in
+ * development only, connects the dev server to Fimo's hosted preview gateway.
  * The platform supplies allowed preview origins at runtime, so applications do
  * not need to know which preview provider Fimo currently uses.
  */
@@ -18,7 +29,7 @@ export function withFimo(applicationConfig) {
         const config = typeof applicationConfig === 'function'
             ? await applicationConfig(phase, context)
             : applicationConfig;
-        if (phase !== NEXT_DEVELOPMENT_PHASE) {
+        if (!RUNTIME_ENV_PHASES.has(phase)) {
             return config;
         }
         // Next has already loaded `.env*` into `process.env` by the time this runs,
@@ -26,9 +37,11 @@ export function withFimo(applicationConfig) {
         // env files supplied it — only then does the git branch decide, per key.
         const derived = resolveLocalRuntimeEnv({ cwd: process.cwd() });
         if (derived) {
-            const stale = findStaleFimoOverride(process.env, derived);
-            if (stale) {
-                console.warn(staleOverrideMessage(stale));
+            if (phase === NEXT_DEVELOPMENT_PHASE) {
+                const stale = findStaleFimoOverride(process.env, derived);
+                if (stale) {
+                    console.warn(staleOverrideMessage(stale));
+                }
             }
             for (const [key, value] of Object.entries(derived.values)) {
                 if (!process.env[key]) {
@@ -36,6 +49,9 @@ export function withFimo(applicationConfig) {
                 }
             }
         }
+        if (phase !== NEXT_DEVELOPMENT_PHASE) {
+            return config;
+        }
         const previewOrigins = readPreviewOrigins();
         if (previewOrigins.length === 0) {
             return config;

package/dist/build/sveltekit/vite.d.ts

@@ -1,11 +1,10 @@
 import type { PluginOption } from 'vite';
 /**
- * Narrow SvelteKit build connector. Points the dev server at the git branch's
- * Fimo env (`PUBLIC_FIMO_API_URL`, `FIMO_ENV`), and tags native Svelte
+ * Narrow SvelteKit build connector. Points dev and production builds at the
+ * git branch's Fimo env (`PUBLIC_FIMO_API_URL`, `FIMO_ENV`), and tags native Svelte
  * template elements with deterministic `data-fimo-id="<path>#<line>-<column>"`
  * attributes during `vite dev` so the Fimo preview can map DOM nodes back to
- * source. Explicit `data-fimo-id` attributes are preserved and production
- * builds are untouched.
+ * source. Explicit `data-fimo-id` attributes are preserved.
  *
  * Usage in the app's vite.config.ts: `plugins: [fimo(), sveltekit()]`.
  */

package/dist/build/sveltekit/vite.js

@@ -1,12 +1,11 @@
 import runtimeEnvPlugin from '../vite/plugins/runtime-env.js';
 import svelteDataIdPlugin from './data-id.js';
 /**
- * Narrow SvelteKit build connector. Points the dev server at the git branch's
- * Fimo env (`PUBLIC_FIMO_API_URL`, `FIMO_ENV`), and tags native Svelte
+ * Narrow SvelteKit build connector. Points dev and production builds at the
+ * git branch's Fimo env (`PUBLIC_FIMO_API_URL`, `FIMO_ENV`), and tags native Svelte
  * template elements with deterministic `data-fimo-id="<path>#<line>-<column>"`
  * attributes during `vite dev` so the Fimo preview can map DOM nodes back to
- * source. Explicit `data-fimo-id` attributes are preserved and production
- * builds are untouched.
+ * source. Explicit `data-fimo-id` attributes are preserved.
  *
  * Usage in the app's vite.config.ts: `plugins: [fimo(), sveltekit()]`.
  */

package/dist/build/vite/plugins/runtime-env.d.ts

@@ -5,7 +5,8 @@ import { type Plugin } from 'vite';
  * One rule, per variable: anything already set — by the process env (sandbox,
  * shell) or the user's own `.env*` files, read through Vite's `loadEnv` — is
  * left alone; derivation fills only what is missing. A value a user wrote by
- * hand is an override, and this plugin must never win over it.
+ * hand is an override, and this plugin must never win over it. Empty or
+ * `undefined` `define` placeholders generated from a missing env are not values.
  *
  * Two injection paths, both needed:
  * - `process.env`, so Vite's own `VITE_*` exposure, `loadEnv`, and server-side

package/dist/build/vite/plugins/runtime-env.js

@@ -6,7 +6,8 @@ import { findStaleFimoOverride, resolveLocalRuntimeEnv, staleOverrideMessage, }
  * One rule, per variable: anything already set — by the process env (sandbox,
  * shell) or the user's own `.env*` files, read through Vite's `loadEnv` — is
  * left alone; derivation fills only what is missing. A value a user wrote by
- * hand is an override, and this plugin must never win over it.
+ * hand is an override, and this plugin must never win over it. Empty or
+ * `undefined` `define` placeholders generated from a missing env are not values.
  *
  * Two injection paths, both needed:
  * - `process.env`, so Vite's own `VITE_*` exposure, `loadEnv`, and server-side
@@ -33,24 +34,27 @@ export default function runtimeEnvPlugin() {
             // `import.meta.env`, which `define` patches at transform time.
             order: 'pre',
             handler(config, { command, mode }) {
-                // Production builds get their env from the platform. Only a local dev
-                // server has a git branch worth deriving from.
-                if (command !== 'serve') {
-                    return;
-                }
                 const cwd = config.root ?? process.cwd();
                 const derived = resolveLocalRuntimeEnv({ cwd });
                 if (!derived) {
                     return;
                 }
                 const explicit = { ...loadEnv(mode, config.envDir ?? cwd, ''), ...process.env };
-                const stale = findStaleFimoOverride(explicit, derived);
-                if (stale) {
-                    console.warn(staleOverrideMessage(stale));
+                if (command === 'serve') {
+                    const stale = findStaleFimoOverride(explicit, derived);
+                    if (stale) {
+                        console.warn(staleOverrideMessage(stale));
+                    }
                 }
                 // Decide what is missing BEFORE writing to process.env, or the define
                 // step below would see the values this loop just set.
-                const missing = Object.entries(derived.values).filter(([key]) => !explicit[key]);
+                const missing = Object.entries(derived.values).filter(([key]) => {
+                    if (explicit[key]) {
+                        return false;
+                    }
+                    const defined = config.define?.[`import.meta.env.${key}`];
+                    return defined === undefined || defined === 'undefined' || defined === JSON.stringify('');
+                });
                 for (const [key, value] of missing) {
                     process.env[key] = value;
                 }

package/dist/cli/bundle.json

@@ -1,8 +1,8 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-19T19:12:35.442Z",
-  "cliVersion": "0.17.0",
+  "bundledAt": "2026-08-21T13:51:41.500Z",
+  "cliVersion": "0.19.0",
   "external": [
     "oxc-parser",
     "fsevents",