mfeflow 0.0.0-stage → 0.2.0

package/assets/features/telemetry-otel/feature.json

@@ -0,0 +1,159 @@
+{
+  "name": "telemetry-otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry for the browser behind @mfeflow/telemetry: spans per remote tagged with mfe.name, fetch tracing with trace headers, web vitals and remote failures sent to an OTLP endpoint. The SDK loads after first render; endpoint, sampling and CORS origins come from the runtime config.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "src/telemetry/init.ts",
+      "target": "shell",
+      "from": "files/init.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/telemetry/init.test.ts",
+      "target": "shell",
+      "from": "files/shell-init-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/telemetry.ts",
+      "target": "remotes",
+      "from": "files/remote-telemetry.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/telemetry.test.ts",
+      "target": "remotes",
+      "from": "files/remote-telemetry-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/telemetry",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/telemetry",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "initTelemetryFromConfig",
+      "from": "./telemetry/init",
+      "await": false
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "otlpEndpoint",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().regex(/^(https?:[/][/][^\\s]+)?$/)",
+        "valibot": "v.pipe(v.string(), v.regex(/^(https?:[/][/][^\\s]+)?$/))",
+        "arktype": "\"'' | string.url\""
+      },
+      "value": "",
+      "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": "src/config/schema.ts",
+      "target": "shell",
+      "key": "traceSampleRatio",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.number().min(0).max(1)",
+        "valibot": "v.pipe(v.number(), v.minValue(0), v.maxValue(1))",
+        "arktype": "'0 <= number <= 1'"
+      },
+      "value": 1,
+      "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": "src/config/schema.ts",
+      "target": "shell",
+      "key": "propagateTraceHeaderCorsUrls",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.array(z.string())",
+        "valibot": "v.array(v.string())",
+        "arktype": "'string[]'"
+      },
+      "value": [],
+      "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": "otlpEndpoint",
+      "scope": "runtime",
+      "schema": "z.string().regex(/^(https?:[/][/][^\\s]+)?$/)",
+      "value": "",
+      "when": {
+        "feature:env-t3": false
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "public/config/runtime-config.json",
+      "target": "shell",
+      "key": "traceSampleRatio",
+      "scope": "runtime",
+      "schema": "z.number().min(0).max(1)",
+      "value": 1,
+      "when": {
+        "feature:env-t3": false
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "public/config/runtime-config.json",
+      "target": "shell",
+      "key": "propagateTraceHeaderCorsUrls",
+      "scope": "runtime",
+      "schema": "z.array(z.string())",
+      "value": [],
+      "when": {
+        "feature:env-t3": false
+      }
+    }
+  ]
+}

package/assets/features/telemetry-otel/files/init.ts.eta

@@ -0,0 +1,53 @@
+/* oxlint-disable eslint/no-underscore-dangle -- __MFEFLOW_APP_VERSION__ is the name the rsbuild preset defines */
+import { initTelemetry } from '@mfeflow/telemetry';
+import { fetchRuntimeConfig } from '@mfeflow/runtime';
+
+// The shell's rsbuild preset replaces this with the version in package.json at build time.
+declare const __MFEFLOW_APP_VERSION__: string | undefined;
+const APP_VERSION =
+  typeof __MFEFLOW_APP_VERSION__ === 'string' ? __MFEFLOW_APP_VERSION__ : 'unknown';
+
+const strings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+/**
+ * Starts telemetry from the runtime config. With no `otlpEndpoint` it stays off. The OpenTelemetry
+ * SDK is a separate chunk that loads after the page has loaded and the browser is idle, so it is
+ * never on the path to first render.
+ */
+export async function startTelemetry(): Promise<void> {
+  const config = await fetchRuntimeConfig().catch((error: unknown) => {
+    console.warn('[telemetry] the runtime config did not load, so telemetry stays off', error);
+    return undefined;
+  });
+  if (config === undefined) return;
+  const { otlpEndpoint, traceSampleRatio, environment } = config;
+  if (typeof otlpEndpoint !== 'string' || otlpEndpoint === '') return;
+  try {
+    initTelemetry(
+      async () => {
+        const { createOtelProvider } = await import('@mfeflow/telemetry/otel');
+        return createOtelProvider({
+          serviceName: '<%= it.app.name %>',
+          version: APP_VERSION,
+          environment: typeof environment === 'string' ? environment : 'unknown',
+          otlpEndpoint,
+          sampleRatio: typeof traceSampleRatio === 'number' ? traceSampleRatio : undefined,
+          propagateTraceHeaderCorsUrls: strings(config.propagateTraceHeaderCorsUrls),
+        });
+      },
+      {
+        onError: (error) => {
+          console.warn('[telemetry] not started', error);
+        },
+      },
+    );
+  } catch (error) {
+    console.warn('[telemetry] not started', error);
+  }
+}
+
+/** The boot step: starts telemetry without holding up first render. */
+export function initTelemetryFromConfig(): void {
+  void startTelemetry();
+}

package/assets/features/telemetry-otel/files/remote-telemetry-test.ts.eta

@@ -0,0 +1,13 @@
+import { resetTelemetryForTests } from '@mfeflow/telemetry';
+import { afterEach, describe, expect, it } from 'vitest';
+import { tracer } from './telemetry';
+
+afterEach(resetTelemetryForTests);
+
+describe('the <%= it.app.name %> tracer', () => {
+  it('can be used before the shell has started telemetry, and records nothing', () => {
+    const span = tracer.startSpan('work');
+    expect(span.isRecording()).toBe(false);
+    span.end();
+  });
+});

package/assets/features/telemetry-otel/files/remote-telemetry.ts.eta

@@ -0,0 +1,11 @@
+import { getTracer } from '@mfeflow/telemetry';
+
+// Spans started with this tracer carry mfe.name = <%= it.app.name %>. Take it once, at import time:
+// it records as soon as the shell has started telemetry.
+//
+//   tracer.startActiveSpan('checkout.click', (span) => {
+//     void fetch('/api/orders').finally(() => span.end());
+//   });
+//
+// Start the fetch inside the callback, before any await: the context follows synchronous calls only.
+export const tracer = getTracer('<%= it.app.name %>');

package/assets/features/telemetry-otel/files/shell-init-test.ts.eta

@@ -0,0 +1,36 @@
+import { isTelemetryReady, resetTelemetryForTests, telemetryReady } from '@mfeflow/telemetry';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { startTelemetry } from './init';
+
+afterEach(() => {
+  Reflect.deleteProperty(globalThis, '__MFE_RUNTIME_CONFIG__');
+  resetTelemetryForTests();
+});
+
+describe('startTelemetry', () => {
+  it('stays off without an otlpEndpoint', async () => {
+    Reflect.set(globalThis, '__MFE_RUNTIME_CONFIG__', { environment: 'dev', otlpEndpoint: '' });
+    await startTelemetry();
+    await telemetryReady();
+    expect(isTelemetryReady()).toBe(false);
+  });
+
+  it('warns, and does not throw, when telemetry cannot start', async () => {
+    vi.resetModules();
+    vi.doMock('@mfeflow/telemetry', async (original) => ({
+      ...(await original<typeof import('@mfeflow/telemetry')>()),
+      initTelemetry: () => {
+        throw new Error('boom');
+      },
+    }));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    Reflect.set(globalThis, '__MFE_RUNTIME_CONFIG__', {
+      otlpEndpoint: 'https://collector.example.com/v1/traces',
+    });
+    const fresh = await import('./init');
+    await expect(fresh.startTelemetry()).resolves.toBeUndefined();
+    expect(warn).toHaveBeenCalledWith('[telemetry] not started', expect.any(Error));
+    warn.mockRestore();
+    vi.doUnmock('@mfeflow/telemetry');
+  });
+});

package/assets/features/testing/feature.json

@@ -0,0 +1,202 @@
+{
+  "name": "testing",
+  "version": "0.1.0",
+  "description": "Vitest, Testing Library, jsdom and MSW in every app with @mfeflow/testing, and a Playwright smoke test that opens the shell and checks each remote renders.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "vitest.config.ts",
+      "target": "shell",
+      "from": "files/vitest.config.ts"
+    },
+    {
+      "to": "src/test/setup.ts",
+      "target": "shell",
+      "from": "files/setup.ts"
+    },
+    {
+      "to": "src/mocks/handlers.ts",
+      "target": "shell",
+      "from": "files/handlers.ts"
+    },
+    {
+      "to": "src/mocks/server.ts",
+      "target": "shell",
+      "from": "files/server.ts"
+    },
+    {
+      "to": "src/mocks/handlers.test.ts",
+      "target": "shell",
+      "from": "files/sample-handlers-test.ts"
+    },
+    {
+      "to": "src/pages/Home.test.tsx",
+      "target": "shell",
+      "from": "files/sample-shell-test.tsx"
+    },
+    {
+      "to": "vitest.config.ts",
+      "target": "remotes",
+      "from": "files/vitest.config.ts"
+    },
+    {
+      "to": "src/test/setup.ts",
+      "target": "remotes",
+      "from": "files/setup.ts"
+    },
+    {
+      "to": "src/mocks/handlers.ts",
+      "target": "remotes",
+      "from": "files/handlers.ts"
+    },
+    {
+      "to": "src/mocks/server.ts",
+      "target": "remotes",
+      "from": "files/server.ts"
+    },
+    {
+      "to": "src/mocks/handlers.test.ts",
+      "target": "remotes",
+      "from": "files/sample-handlers-test.ts"
+    },
+    {
+      "to": "src/exposed/App.test.tsx",
+      "target": "remotes",
+      "from": "files/sample-remote-test.tsx"
+    },
+    {
+      "to": "vitest.config.ts",
+      "target": "root",
+      "from": "files/root-vitest.config.ts"
+    },
+    {
+      "to": "playwright.config.ts",
+      "target": "root",
+      "from": "files/playwright.config.ts"
+    },
+    {
+      "to": "e2e/smoke.spec.ts",
+      "target": "root",
+      "from": "files/sample-smoke-e2e.ts"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "vitest",
+      "range": "5.0.5",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "jsdom",
+      "range": "30.1.3",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@testing-library/react",
+      "range": "16.3.3",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@testing-library/dom",
+      "range": "10.4.2",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "msw",
+      "range": "3.0.3",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@mfeflow/testing",
+      "range": "latest",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "vitest",
+      "range": "5.0.5",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "jsdom",
+      "range": "30.1.3",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@testing-library/react",
+      "range": "16.3.3",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@testing-library/dom",
+      "range": "10.4.2",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "msw",
+      "range": "3.0.3",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@mfeflow/testing",
+      "range": "latest",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "vitest",
+      "range": "5.0.5",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@playwright/test",
+      "range": "1.64.1",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@types/node",
+      "range": "26.6.6",
+      "target": "root",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "test",
+      "command": "vitest run",
+      "target": "shell"
+    },
+    {
+      "name": "test",
+      "command": "vitest run",
+      "target": "remotes"
+    },
+    {
+      "name": "test",
+      "command": "vitest run",
+      "target": "root"
+    },
+    {
+      "name": "test:e2e",
+      "command": "playwright test",
+      "target": "root"
+    },
+    {
+      "name": "typecheck:tooling",
+      "command": "tsc --noEmit",
+      "target": "root"
+    }
+  ]
+}

package/assets/features/testing/files/handlers.ts

@@ -0,0 +1,5 @@
+import { http, HttpResponse } from 'msw';
+
+// Requests a test makes are answered here. Add the endpoints your app calls;
+// a request nothing answers fails the test (see src/test/setup.ts).
+export const handlers = [http.get('*/api/health', () => HttpResponse.json({ ok: true }))];

package/assets/features/testing/files/playwright.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Set BASE_URL to test a deployed shell (a preview, staging); otherwise `pnpm dev` is started here.
+const baseURL = process.env.BASE_URL ?? 'http://localhost:4300';
+
+export default defineConfig({
+  testDir: 'e2e',
+  outputDir: 'node_modules/.cache/playwright/results',
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 1 : 0,
+  reporter: process.env.CI
+    ? [
+        ['github'],
+        ['html', { open: 'never', outputFolder: 'node_modules/.cache/playwright/report' }],
+      ]
+    : 'list',
+  use: { baseURL, trace: 'on-first-retry' },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+  ...(process.env.BASE_URL
+    ? {}
+    : {
+        webServer: {
+          command: 'pnpm dev',
+          url: baseURL,
+          reuseExistingServer: !process.env.CI,
+          gracefulShutdown: { signal: 'SIGTERM', timeout: 10_000 },
+          timeout: 120_000,
+        },
+      }),
+});

package/assets/features/testing/files/root-vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config';
+
+// `pnpm test` runs every app's own vitest config in one go.
+export default defineConfig({
+  test: { projects: ['apps/*'] },
+});

package/assets/features/testing/files/sample-handlers-test.ts

@@ -0,0 +1,16 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+import { server } from './server';
+
+describe('mock server', () => {
+  it('answers the default handlers', async () => {
+    const response = await fetch('http://localhost/api/health');
+    expect(await response.json()).toEqual({ ok: true });
+  });
+
+  it('lets a test replace a handler for that test only', async () => {
+    server.use(http.get('*/api/health', () => HttpResponse.json({ ok: false })));
+    const response = await fetch('http://localhost/api/health');
+    expect(await response.json()).toEqual({ ok: false });
+  });
+});

package/assets/features/testing/files/sample-remote-test.tsx

@@ -0,0 +1,12 @@
+import { fireEvent, screen } from '@testing-library/react';
+import { renderWithPlatform } from '@mfeflow/testing';
+import { describe, expect, it } from 'vitest';
+import App from './App';
+
+describe('the exposed App', () => {
+  it('counts clicks', () => {
+    renderWithPlatform(<App />);
+    fireEvent.click(screen.getByRole('button', { name: 'Clicked 0 times' }));
+    expect(screen.getByRole('button', { name: 'Clicked 1 times' })).toBeDefined();
+  });
+});

package/assets/features/testing/files/sample-shell-test.tsx

@@ -0,0 +1,11 @@
+import { screen } from '@testing-library/react';
+import { renderWithPlatform } from '@mfeflow/testing';
+import { describe, expect, it } from 'vitest';
+import { Home } from './Home';
+
+describe('Home', () => {
+  it('says so when the registry listed no remotes', () => {
+    renderWithPlatform(<Home />);
+    expect(screen.getByText(/No remotes yet/)).toBeDefined();
+  });
+});

package/assets/features/testing/files/sample-smoke-e2e.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import { expect, test } from '@playwright/test';
+
+// The remotes the dev registry lists; each one's App carries data-testid="<name>".
+const remotes = fs
+  .readdirSync('registry/envs/dev')
+  .filter((file) => file.endsWith('.json'))
+  .map((file) => file.slice(0, -'.json'.length))
+  .toSorted();
+
+// With env-t3 the shell fetches /config/runtime-config.json at boot and keeps it on globalThis.
+const hasRuntimeConfig = fs.existsSync('scripts/check-runtime-config.ts');
+
+test('the shell loads cleanly, with its runtime config', async ({ page }) => {
+  const problems: string[] = [];
+  page.on('pageerror', (error) => problems.push(`page error: ${error.message}`));
+  page.on('console', (message) => {
+    if (message.type() === 'error') problems.push(`console error: ${message.text()}`);
+  });
+  page.on('requestfailed', (request) =>
+    problems.push(
+      `request failed: ${request.url()} (${request.failure()?.errorText ?? 'unknown'})`,
+    ),
+  );
+  page.on('response', (response) => {
+    if (response.status() >= 400 && !response.url().endsWith('/favicon.ico')) {
+      problems.push(`${String(response.status())} ${response.url()}`);
+    }
+  });
+  await page.goto('/');
+  await expect(page.locator('header')).toBeVisible();
+  if (hasRuntimeConfig) {
+    await expect
+      .poll(() =>
+        page.evaluate(() => {
+          const config: unknown = Reflect.get(globalThis, '__MFE_RUNTIME_CONFIG__');
+          return typeof config === 'object' && config !== null && 'environment' in config
+            ? config.environment
+            : undefined;
+        }),
+      )
+      .toBeTruthy();
+  }
+  await page.waitForLoadState('networkidle');
+  expect(problems).toEqual([]);
+});
+
+for (const name of remotes) {
+  test(`the shell renders ${name}`, async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByTestId(name)).toBeVisible();
+  });
+}

package/assets/features/testing/files/server.ts

@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);

package/assets/features/testing/files/setup.ts

@@ -0,0 +1,18 @@
+import { cleanup } from '@testing-library/react';
+import { resetPlatform } from '@mfeflow/testing';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import { server } from '../mocks/server';
+
+beforeAll(() => {
+  server.listen({ onUnhandledFrame: 'error' });
+});
+
+afterEach(() => {
+  cleanup();
+  resetPlatform();
+  server.resetHandlers();
+});
+
+afterAll(() => {
+  server.close();
+});

package/assets/features/testing/files/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  // One copy of React and Testing Library, also when a package like @mfeflow/testing is linked from another folder.
+  resolve: { dedupe: ['react', 'react-dom', '@testing-library/react', '@testing-library/dom'] },
+  test: {
+    environment: 'jsdom',
+    include: ['src/**/*.test.{ts,tsx}'],
+    setupFiles: ['./src/test/setup.ts'],
+  },
+});