mfeflow 0.1.0 → 0.2.0

package/assets/features/ci-github/files/ci.md

@@ -1,7 +1,7 @@
 # CI
 
 `.github/workflows/ci.yml` runs on every pull request: lint, formatting, typecheck, tests, build, then
-`mfeflow doctor`, `validate`, `check-compat` and `budget`, the runtime-config check and the Playwright smoke test.
+`pnpm mfeflow doctor`, `validate`, `check-compat` and `budget`, the runtime-config check and the Playwright smoke test.
 A step for a feature the project does not have is skipped, so adding `testing` or `env-t3` later needs no edit to the
 workflow. Every action is pinned to a commit SHA, the workflow starts from `permissions: {}`, and the job gets
 `contents: read` only. Dependabot or Renovate can keep the pins current.

package/assets/features/ci-github/files/ci.yml

@@ -39,13 +39,13 @@ jobs:
         run: pnpm run --if-present test
       - run: pnpm build
       - name: mfeflow doctor
-        run: pnpm exec mfeflow doctor
+        run: pnpm mfeflow doctor
       - name: mfeflow validate
-        run: pnpm exec mfeflow validate
+        run: pnpm mfeflow validate
       - name: mfeflow check-compat
-        run: pnpm exec mfeflow check-compat
+        run: pnpm mfeflow check-compat
       - name: mfeflow budget
-        run: pnpm exec mfeflow budget
+        run: pnpm mfeflow budget
       - name: Check runtime config
         run: pnpm run --if-present check:runtime-config
       - name: Install Playwright browser

package/assets/features/env-t3/feature.json

@@ -373,6 +373,27 @@
       "when": {
         "feature:telemetry-otel": true
       }
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().min(1)",
+        "valibot": "v.pipe(v.string(), v.minLength(1))",
+        "arktype": "'string > 0'"
+      },
+      "value": "/api",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:http": true
+      }
     }
   ]
 }

package/assets/features/env-t3/files/env.arktype.ts

@@ -2,7 +2,7 @@ import { createEnv } from '@t3-oss/env-core';
 import { type } from 'arktype';
 
 // Server and build-time variables, checked when a process that imports this file starts.
-// Add one: mfeflow add env-key API_ORIGIN --scope server --schema "type('string.url')"
+// Add one: pnpm mfeflow add env-key API_ORIGIN --scope server --schema "type('string.url')"
 export const env = createEnv({
   server: {
     NODE_ENV: type("'development' | 'production' | 'test' | undefined"),

package/assets/features/env-t3/files/env.valibot.ts

@@ -2,7 +2,7 @@ import { createEnv } from '@t3-oss/env-core';
 import * as v from 'valibot';
 
 // Server and build-time variables, checked when a process that imports this file starts.
-// Add one: mfeflow add env-key API_ORIGIN --scope server --schema "v.pipe(v.string(), v.url())"
+// Add one: pnpm mfeflow add env-key API_ORIGIN --scope server --schema "v.pipe(v.string(), v.url())"
 export const env = createEnv({
   server: {
     NODE_ENV: v.optional(v.picklist(['development', 'production', 'test'])),

package/assets/features/env-t3/files/env.zod.ts

@@ -2,7 +2,7 @@ import { createEnv } from '@t3-oss/env-core';
 import { z } from 'zod';
 
 // Server and build-time variables, checked when a process that imports this file starts.
-// Add one: mfeflow add env-key API_ORIGIN --scope server --schema "z.url()"
+// Add one: pnpm mfeflow add env-key API_ORIGIN --scope server --schema "z.url()"
 export const env = createEnv({
   server: {
     NODE_ENV: z.enum(['development', 'production', 'test']).optional(),

package/assets/features/env-t3/files/schema.arktype.ts

@@ -2,7 +2,7 @@ import { type } from 'arktype';
 
 // The shape of public/config/runtime-config.<env>.json. The browser only imports this file's type
 // (see ./runtime), so the validator stays out of the bundle; `pnpm check:runtime-config` validates the files.
-// Add a key: mfeflow add env-key GTM_ID --scope runtime --schema "type('string > 0')"
+// Add a key: pnpm mfeflow add env-key GTM_ID --scope runtime --schema "type('string > 0')"
 export const runtimeConfigSchema = type({
   environment: "'dev' | 'staging' | 'prod'",
 });

package/assets/features/env-t3/files/schema.valibot.ts

@@ -2,7 +2,7 @@ import * as v from 'valibot';
 
 // The shape of public/config/runtime-config.<env>.json. The browser only imports this file's type
 // (see ./runtime), so the validator stays out of the bundle; `pnpm check:runtime-config` validates the files.
-// Add a key: mfeflow add env-key GTM_ID --scope runtime --schema "v.pipe(v.string(), v.minLength(1))"
+// Add a key: pnpm mfeflow add env-key GTM_ID --scope runtime --schema "v.pipe(v.string(), v.minLength(1))"
 export const runtimeConfigSchema = v.object({
   environment: v.picklist(['dev', 'staging', 'prod']),
 });

package/assets/features/env-t3/files/schema.zod.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 // The shape of public/config/runtime-config.<env>.json. The browser only imports this file's type
 // (see ./runtime), so the validator stays out of the bundle; `pnpm check:runtime-config` validates the files.
-// Add a key: mfeflow add env-key GTM_ID --scope runtime --schema "z.string().min(1)"
+// Add a key: pnpm mfeflow add env-key GTM_ID --scope runtime --schema "z.string().min(1)"
 export const runtimeConfigSchema = z.object({
   environment: z.enum(['dev', 'staging', 'prod']),
 });

package/assets/features/event-bus/feature.json

@@ -0,0 +1,100 @@
+{
+  "name": "event-bus",
+  "version": "0.1.0",
+  "description": "Typed events between remotes (@mfeflow/event-bus) and the contracts package that holds their types: packages/contracts/src/events, merged into the bus in every app, with a sample event.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "packages/contracts/package.json",
+      "target": "root",
+      "from": "files/contracts-package.json.eta",
+      "template": true
+    },
+    {
+      "to": "packages/contracts/src/events/index.ts",
+      "target": "root",
+      "from": "files/contracts-events.ts"
+    },
+    {
+      "to": "packages/contracts/README.md",
+      "target": "root",
+      "from": "files/contracts-readme.md"
+    },
+    {
+      "to": "src/events.ts",
+      "target": "shell",
+      "from": "files/shell-events.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/events.test.ts",
+      "target": "shell",
+      "from": "files/shell-events-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/events.ts",
+      "target": "remotes",
+      "from": "files/events.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/events.test.ts",
+      "target": "remotes",
+      "from": "files/events-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/Announce.tsx",
+      "target": "remotes",
+      "from": "files/announce.tsx.eta",
+      "template": true
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/event-bus",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/event-bus",
+      "range": "latest",
+      "target": "remotes"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "workspace:*",
+      "target": "shell"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "workspace:*",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "configureShellEvents",
+      "from": "./events",
+      "await": false
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/exposed/App.tsx",
+      "target": "remotes",
+      "component": "Announce",
+      "from": "../Announce",
+      "function": "App"
+    }
+  ]
+}

package/assets/features/event-bus/files/announce.tsx.eta

@@ -0,0 +1,10 @@
+import { useEffect, type ReactNode } from 'react';
+import { announceReady } from './events';
+
+/** Tells the other remotes that <%= it.app.name %> is on the page, each time it mounts. */
+export function Announce({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    announceReady();
+  }, []);
+  return <>{children}</>;
+}

package/assets/features/event-bus/files/contracts-events.ts

@@ -0,0 +1,11 @@
+/**
+ * Every event the platform can carry, by versioned name: <domain>.<event>.v<major>, like
+ * cart.item-added.v1. Types only: nothing here runs, so any remote can read it.
+ *
+ * Add an event by adding a line. Change a payload in a way old listeners cannot read by adding
+ * a new version (cart.item-added.v2) and publishing both until every listener has moved.
+ */
+export interface Events {
+  /** A remote is on the page. The sample event: every remote announces itself, every other one can listen. */
+  'mfe.ready.v1': { mfe: string };
+}

package/assets/features/event-bus/files/contracts-package.json.eta

@@ -0,0 +1,10 @@
+{
+  "name": "<%= it.scope %>/contracts",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./events": "./src/events/index.ts",
+    "./routes/*": "./src/routes/*.ts"
+  }
+}

package/assets/features/event-bus/files/contracts-readme.md

@@ -0,0 +1,10 @@
+# contracts
+
+What the micro-frontends agree on, and nothing else. A remote never imports another remote; it
+imports this.
+
+- `src/events`: the events remotes publish and listen to, as types.
+- `src/routes`: each remote's public paths, as plain data (added by `route-factory`).
+
+Keep it to types and plain data with no imports, so reading it costs a remote nothing at run time
+and it never pulls in another remote's code.

package/assets/features/event-bus/files/events-test.ts.eta

@@ -0,0 +1,18 @@
+import { publish, resetEventBusForTests } from '@mfeflow/event-bus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { announceReady, onOtherRemoteReady } from './events';
+
+afterEach(resetEventBusForTests);
+
+describe('the <%= it.app.name %> events', () => {
+  it('hears another remote and not itself', () => {
+    const heard = vi.fn();
+    const stop = onOtherRemoteReady(heard);
+    announceReady();
+    publish('mfe.ready.v1', { mfe: 'somewhere-else' });
+    expect(heard).toHaveBeenCalledExactlyOnceWith('somewhere-else');
+    stop();
+    publish('mfe.ready.v1', { mfe: 'later' });
+    expect(heard).toHaveBeenCalledOnce();
+  });
+});

package/assets/features/event-bus/files/events.ts.eta

@@ -0,0 +1,20 @@
+import { publish, subscribe } from '@mfeflow/event-bus';
+import type { Events } from '<%= it.scope %>/contracts/events';
+
+// The platform's event map is the contracts package's. This one declaration merges it in.
+declare module '@mfeflow/event-bus' {
+  // oxlint-disable-next-line typescript/no-empty-interface -- merges the contracts into the platform map
+  interface EventMap extends Events {}
+}
+
+/** Tells the other remotes that <%= it.app.name %> is on the page. */
+export function announceReady(): void {
+  publish('mfe.ready.v1', { mfe: '<%= it.app.name %>' });
+}
+
+/** Calls `handler` with the name of each other remote that announces itself. Returns the function that stops it. */
+export function onOtherRemoteReady(handler: (mfe: string) => void): () => void {
+  return subscribe('mfe.ready.v1', ({ mfe }) => {
+    if (mfe !== '<%= it.app.name %>') handler(mfe);
+  });
+}

package/assets/features/event-bus/files/shell-events-test.ts.eta

@@ -0,0 +1,22 @@
+import { publish, resetEventBusForTests, subscribe } from '@mfeflow/event-bus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { configureShellEvents } from './events';
+
+afterEach(resetEventBusForTests);
+
+describe('the shell event bus', () => {
+  it('carries the contracts events between remotes', () => {
+    const heard = vi.fn();
+    subscribe('mfe.ready.v1', heard);
+    publish('mfe.ready.v1', { mfe: 'cart' });
+    expect(heard).toHaveBeenCalledExactlyOnceWith({ mfe: 'cart' });
+  });
+
+  it('replays the latest announcement to a remote that mounts late', () => {
+    configureShellEvents();
+    publish('mfe.ready.v1', { mfe: 'cart' });
+    const late = vi.fn();
+    subscribe('mfe.ready.v1', late);
+    expect(late).toHaveBeenCalledExactlyOnceWith({ mfe: 'cart' });
+  });
+});

package/assets/features/event-bus/files/shell-events.ts.eta

@@ -0,0 +1,19 @@
+import { configureEvent } from '@mfeflow/event-bus';
+import type { Events } from '<%= it.scope %>/contracts/events';
+
+// The platform's event map is the contracts package's. This one declaration merges it in.
+declare module '@mfeflow/event-bus' {
+  // oxlint-disable-next-line typescript/no-empty-interface -- merges the contracts into the platform map
+  interface EventMap extends Events {}
+}
+
+/**
+ * How the platform's events behave, set once at boot. The shell imports the bus here, which makes
+ * it the one that provides the copy every remote shares.
+ */
+export function configureShellEvents(): void {
+  // "This remote is up" is a fact about the page, not a moment: a remote that mounts later still
+  // hears the latest announcement. Only the last one is kept. Leave replay off for events that
+  // are things that happened, like cart.item-added.v1.
+  configureEvent('mfe.ready.v1', { replay: true });
+}

package/assets/features/http/feature.json

@@ -0,0 +1,81 @@
+{
+  "name": "http",
+  "version": "0.1.0",
+  "description": "A fetch client over your url-factory endpoints (@mfeflow/http): src/api/client.ts in every app, with retries for idempotent requests, timeouts and typed errors. The API base URL is the runtime config's apiUrl.",
+  "requires": ["core", "tsconfig", "url-factory"],
+  "files": [
+    {
+      "to": "src/api/client.ts",
+      "target": "shell",
+      "from": "files/client.ts"
+    },
+    {
+      "to": "src/api/client.ts",
+      "target": "remotes",
+      "from": "files/client.ts"
+    },
+    {
+      "to": "src/api/client.test.ts",
+      "target": "shell",
+      "from": "files/client-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/api/client.test.ts",
+      "target": "remotes",
+      "from": "files/client-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/http",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/http",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().min(1)",
+        "valibot": "v.pipe(v.string(), v.minLength(1))",
+        "arktype": "'string > 0'"
+      },
+      "value": "/api",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:env-t3": true
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "public/config/runtime-config.json",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": "z.string().min(1)",
+      "value": "/api",
+      "when": {
+        "feature:env-t3": false
+      }
+    }
+  ]
+}

package/assets/features/http/files/client-test.ts

@@ -0,0 +1,19 @@
+import { isHttpError } from '@mfeflow/http';
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+import { server } from '../mocks/server';
+import { api } from './client';
+
+describe('the api client', () => {
+  it('reads an endpoint through the mock server', async () => {
+    expect(await api.get('health')).toEqual({ ok: true });
+  });
+
+  it('turns a failure into an HttpError with the status', async () => {
+    server.use(
+      http.get('*/api/health', () => HttpResponse.json({ error: 'down' }, { status: 404 })),
+    );
+    const error = await api.get('health').catch((e: unknown) => e);
+    expect(isHttpError(error) && error.status).toBe(404);
+  });
+});

package/assets/features/http/files/client.ts

@@ -0,0 +1,20 @@
+import { createHttpClient } from '@mfeflow/http';
+import { apiUrl, type endpoints } from './endpoints';
+
+// What each endpoint answers with, by the name in ./endpoints. Add a line per endpoint you call.
+interface Responses {
+  health: { ok: boolean };
+}
+
+/**
+ * One client per app over the endpoints in ./endpoints. The base URL is the runtime config's
+ * `apiUrl`. Idempotent requests retry on a network error, a timeout and a 502, 503 or 504; a
+ * failure is an HttpError with the status and body, and no URL in its message.
+ *
+ *   const { ok } = await api.get('health');
+ */
+export const api = createHttpClient<typeof endpoints, Responses>({
+  url: apiUrl,
+  // Return the signed-in user's token; no header is sent while this returns undefined.
+  // getToken: () => session.accessToken(),
+});

package/assets/features/route-factory/feature.json

@@ -0,0 +1,60 @@
+{
+  "name": "route-factory",
+  "version": "0.1.0",
+  "description": "Typed links between remotes (@mfeflow/route-factory): src/routes.ts in every remote. With event-bus the paths live in the contracts package, so remotes link to each other without importing each other.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "src/routes.ts",
+      "target": "remotes",
+      "from": "files/routes.ts.eta",
+      "template": true,
+      "when": {
+        "feature:event-bus": false
+      }
+    },
+    {
+      "to": "src/routes.ts",
+      "target": "remotes",
+      "from": "files/routes-contract.ts.eta",
+      "template": true,
+      "when": {
+        "feature:event-bus": true
+      }
+    },
+    {
+      "to": "packages/contracts/src/routes/{{app.name}}.ts",
+      "target": "remotes",
+      "atRoot": true,
+      "from": "files/contract.ts.eta",
+      "template": true,
+      "when": {
+        "feature:event-bus": true
+      }
+    },
+    {
+      "to": "src/routes.test.ts",
+      "target": "remotes",
+      "from": "files/routes-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/route-factory",
+      "range": "latest",
+      "target": "remotes"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "workspace:*",
+      "target": "remotes",
+      "when": {
+        "feature:event-bus": true
+      }
+    }
+  ]
+}

package/assets/features/route-factory/files/contract.ts.eta

@@ -0,0 +1,7 @@
+/**
+ * <%= it.app.name %>'s public paths, as plain data: no imports, so any remote can read them.
+ * `:id` is a path param; `?q&page?` after the path names search params (q is required).
+ */
+export const routes = {
+  home: '/',
+} as const;

package/assets/features/route-factory/files/routes-contract.ts.eta

@@ -0,0 +1,11 @@
+import { createLinks, defineRoutes } from '@mfeflow/route-factory';
+import { routes as contract } from '<%= it.scope %>/contracts/routes/<%= it.app.name %>';
+
+// The paths are in the contracts package, so another remote can link here without importing this
+// one. `/<%= it.app.name %>` is where the shell serves this remote.
+export const routes = defineRoutes('/<%= it.app.name %>', contract);
+
+// Links to this remote's routes. Another remote links here with
+//   import { routes as <%= it.app.name %> } from '<%= it.scope %>/contracts/routes/<%= it.app.name %>'
+// and createLinks({ <%= it.app.name %>: defineRoutes('/<%= it.app.name %>', <%= it.app.name %>) }).
+export const links = createLinks({ <%= it.app.name %>: routes });

package/assets/features/route-factory/files/routes-test.ts.eta

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import { links, routes } from './routes';
+
+describe('the <%= it.app.name %> routes', () => {
+  it('are served under /<%= it.app.name %>', () => {
+    expect(routes.mount).toBe('/<%= it.app.name %>');
+    expect(links.href('<%= it.app.name %>.home')).toBe('/<%= it.app.name %>');
+  });
+});

package/assets/features/route-factory/files/routes.ts.eta

@@ -0,0 +1,11 @@
+import { createLinks, defineRoutes } from '@mfeflow/route-factory';
+
+// <%= it.app.name %>'s public paths. `/<%= it.app.name %>` is where the shell serves this remote.
+// A route is a path template: `:id` is a path param, and `?q&page?` after the path names search
+// params (q is required, page is optional). Links to a route are checked against this table.
+export const routes = defineRoutes('/<%= it.app.name %>', {
+  home: '/',
+});
+
+// Links to this remote's routes. Another remote links here by adding `{ <%= it.app.name %>: routes }` to its own createLinks.
+export const links = createLinks({ <%= it.app.name %>: routes });

package/assets/features/url-factory/files/endpoints.ts

@@ -4,9 +4,20 @@ export const endpoints = defineEndpoints({
   health: { service: 'api', path: '/health' },
 });
 
-const services: Record<string, string> = { api: '/api' };
+const defaults: Record<string, string> = { api: '/api' };
+
+// A service's base is `<service>Url` in the runtime config (apiUrl for api) when the shell loaded
+// one, so a build runs in every environment; the default above is for tests and standalone runs.
+function configured(service: string): string | undefined {
+  const config: unknown = Reflect.get(globalThis, '__MFE_RUNTIME_CONFIG__');
+  const value: unknown =
+    typeof config === 'object' && config !== null
+      ? Reflect.get(config, `${service}Url`)
+      : undefined;
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
 
 export const apiUrl = createUrlFactory(endpoints, (service) => {
-  const base = services[service];
+  const base = configured(service) ?? defaults[service];
   return base === undefined ? undefined : new URL(base, location.origin).toString();
 });

package/assets/templates/monorepo/feature.json

@@ -164,6 +164,12 @@
       "target": "root",
       "dev": true
     },
+    {
+      "name": "mfeflow",
+      "range": "latest",
+      "target": "root",
+      "dev": true
+    },
     {
       "name": "@mfeflow/runtime",
       "range": "latest",
@@ -271,6 +277,26 @@
       "command": "turbo run build",
       "target": "root"
     },
+    {
+      "name": "doctor",
+      "command": "mfeflow doctor",
+      "target": "root"
+    },
+    {
+      "name": "validate",
+      "command": "mfeflow validate",
+      "target": "root"
+    },
+    {
+      "name": "check-compat",
+      "command": "mfeflow check-compat",
+      "target": "root"
+    },
+    {
+      "name": "budget",
+      "command": "mfeflow budget",
+      "target": "root"
+    },
     {
       "name": "dev",
       "command": "rsbuild dev",

package/assets/templates/monorepo/files/root/AGENTS.md.eta

@@ -4,14 +4,14 @@ Guidance for coding agents working in this repo.
 
 - Package manager: pnpm (via corepack). Never npm or yarn. Versions live in the `catalog` of
   `pnpm-workspace.yaml`; add dependencies there and reference them as `catalog:`.
-- `pnpm dev` runs the shell and every remote. `pnpm build` builds all of them. `mfeflow dev` does the same with
+- `pnpm dev` runs the shell and every remote. `pnpm build` builds all of them. `pnpm mfeflow dev` does the same with
   per-app logs and picks up new remotes without a restart.
-- Before finishing: `mfeflow doctor` (and `mfeflow validate`, `mfeflow check-compat`, `mfeflow budget` after a build) must exit 0.
+- Before finishing: `pnpm doctor` (and `pnpm validate`, `pnpm check-compat`, `pnpm budget` after a build) must exit 0.
 - TypeScript 7, strict. Relative imports have no file extension (`./plan`, not `./plan.js`).
 - Each remote is deployed on its own. A remote must not import from another remote or from
   the shell; talk through the registry, events or URLs.
 - A remote's public surface is `src/exposed/`. Everything else is private to it.
-- Add apps and features with the `mfeflow` CLI (`mfeflow add remote <name>`, `mfeflow features`).
+- Add apps and features with the `mfeflow` CLI, installed as a root dev dependency (`pnpm mfeflow add remote <name>`, `pnpm mfeflow features`).
   `mfeflow.json` is the CLI's record of the project; do not edit the file hashes by hand.
 - Shared singletons (react, react-dom, `@mfeflow/runtime`) are provided by the shell. Do not
   bundle your own copy.

package/assets/templates/monorepo/files/root/README.md.eta

@@ -7,7 +7,7 @@ one shell and independently deployable remotes, loaded at runtime through Module
 apps/shell      the host: routes, layout, registry loading
 apps/<remote>   one micro-frontend each, exposing ./App
 registry/envs   which build of each remote every environment serves
-mfeflow.json    what the CLI generated; `mfeflow add` reads and updates it
+mfeflow.json    what the CLI generated; `pnpm mfeflow add` reads and updates it
 ```
 
 ## Run it
@@ -20,28 +20,28 @@ pnpm dev
 `pnpm dev` starts the shell on http://localhost:4300 and every remote on its own port
 (see `registry/envs/dev`). The shell reads that dev registry and renders the remotes.
 
-`mfeflow dev` does the same with a prefixed, coloured log per app, and it follows the project:
-add a remote with `mfeflow add remote checkout` and it starts, and the shell lists it, without a restart.
-Use a remote you already run elsewhere with `mfeflow dev --remote checkout=http://localhost:3001`,
+`pnpm mfeflow dev` does the same with a prefixed, coloured log per app, and it follows the project:
+add a remote with `pnpm mfeflow add remote checkout` and it starts, and the shell lists it, without a restart.
+Use a remote you already run elsewhere with `pnpm mfeflow dev --remote checkout=http://localhost:3001`,
 or run a few apps with `--only shell,catalog`. Ctrl+C stops everything.
 
 ## Change it
 
 ```sh
-mfeflow add remote checkout     # a new remote, its registry files and its shell route
-mfeflow add <feature>           # see `mfeflow features`
+pnpm mfeflow add remote checkout     # a new remote, its registry files and its shell route
+pnpm mfeflow add <feature>           # see `pnpm mfeflow features`
 ```
 
 ## Check it
 
 ```sh
-mfeflow doctor              # singletons, compatibility, config, drift; --fix repairs the safe ones
-mfeflow validate            # mfeflow.json, every mfe.json and every registry entry
-mfeflow check-compat        # each remote's shared ranges against its shell
-mfeflow budget              # after `pnpm build`: first-load JS per shell and remote
+pnpm doctor              # singletons, compatibility, config, drift; `pnpm doctor --fix` repairs the safe ones
+pnpm validate            # mfeflow.json, every mfe.json and every registry entry
+pnpm check-compat        # each remote's shared ranges against its shell
+pnpm budget              # after `pnpm build`: first-load JS per shell and remote
 ```
 
-All of them take `--json` and exit non-zero on errors, so they can run in CI. `mfeflow budget` checks each remote's entry
+Each is a root script for the `mfeflow` CLI in your devDependencies (`pnpm mfeflow <command>` runs it directly). All of them take `--json` and exit non-zero on errors, so they can run in CI. `pnpm budget` checks each remote's entry
 against the 10 KB a remote may add; set `budget.baselineKb` in `mfeflow.json` (your pages built as one app) to check
 the shell against baseline + 32 KB too.
 

package/assets/templates/monorepo/files/shell/src/pages/Home.tsx.eta

@@ -3,7 +3,9 @@ import { RemoteBoundary, registeredRemotes } from '@mfeflow/runtime';
 // Shows every remote the registry listed, so a new remote appears here without a code change.
 export function Home() {
   const remotes = registeredRemotes();
-  if (remotes.length === 0) return <p>No remotes yet. Run `mfeflow add remote &lt;name&gt;`.</p>;
+  if (remotes.length === 0) {
+    return <p>No remotes yet. Run `pnpm mfeflow add remote &lt;name&gt;`.</p>;
+  }
   return remotes.map((remote) => (
     <section key={remote.name}>
       <RemoteBoundary id={`${remote.name}/App`} loading={<p>Loading {remote.name}…</p>} />

package/dist/index.js

@@ -156,6 +156,21 @@ const FIRST_PARTY = [
         always: false,
         default: false
     },
+    {
+        name: 'event-bus',
+        always: false,
+        default: false
+    },
+    {
+        name: 'route-factory',
+        always: false,
+        default: false
+    },
+    {
+        name: 'http',
+        always: false,
+        default: false
+    },
     {
         name: 'ci-github',
         always: false,
@@ -1583,6 +1598,8 @@ const SINGLETON_SPECIFIERS = [
     '@mfeflow/analytics',
     '@mfeflow/analytics/react',
     '@mfeflow/telemetry',
+    '@mfeflow/event-bus',
+    '@mfeflow/event-bus/react',
     '@mfeflow/storage',
     '@mfeflow/storage/react',
     '@mfeflow/theme',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mfeflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Create and grow a React micro-frontend platform: mfeflow init, add remote, add <feature>.",
   "keywords": [
     "micro-frontend",
@@ -49,14 +49,14 @@
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",
-    "@mfeflow/contracts": "0.1.0",
-    "@mfeflow/core": "0.1.0",
+    "@mfeflow/contracts": "0.2.0",
+    "@mfeflow/core": "0.2.0",
     "citty": "0.2.2",
     "semver": "7.8.5",
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@mfeflow/rsbuild": "0.1.0",
+    "@mfeflow/rsbuild": "0.2.0",
     "@rslib/core": "1.0.5",
     "@types/node": "26.6.6",
     "@types/semver": "7.8.0",