mfeflow 0.4.0 → 0.6.0

package/assets/templates/monorepo/feature.json

@@ -1,6 +1,6 @@
 {
   "name": "core",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "description": "The shell, the remotes, the registry and the workspace around them.",
   "files": [
     {
@@ -67,9 +67,9 @@
       "template": true
     },
     {
-      "to": "mfe.json",
+      "to": "mfeflow.app.json",
       "target": "shell",
-      "from": "files/shell/mfe.json.eta",
+      "from": "files/shell/mfeflow.app.json.eta",
       "template": true
     },
     {
@@ -96,6 +96,12 @@
       "from": "files/shell/src/bootstrap.tsx.eta",
       "template": true
     },
+    {
+      "to": "src/assert.ts",
+      "target": "shell",
+      "from": "files/shell/src/assert.ts.eta",
+      "template": true
+    },
     {
       "to": "src/App.tsx",
       "target": "shell",
@@ -115,9 +121,9 @@
       "template": true
     },
     {
-      "to": "mfe.json",
+      "to": "mfeflow.app.json",
       "target": "remotes",
-      "from": "files/remote/mfe.json.eta",
+      "from": "files/remote/mfeflow.app.json.eta",
       "template": true
     },
     {
@@ -317,5 +323,6 @@
       "command": "rsbuild build",
       "target": "remotes"
     }
-  ]
+  ],
+  "migrations": [{ "from": "0.3.0", "to": "0.4.0", "module": "migrations/0.4.0-app-file.mjs" }]
 }

package/assets/templates/monorepo/files/remote/{mfe.json.eta → mfeflow.app.json.eta}

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://mfeflow.github.io/mfeflow/schema/mfeflow-app.json",
   "name": "<%= it.app.name %>",
   "owner": "team-<%= it.app.name %>",
   "shells": ["shell"],

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

@@ -36,7 +36,7 @@ pnpm mfeflow add <feature>           # see `pnpm mfeflow features`
 
 ```sh
 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 validate            # mfeflow.json, every mfeflow.app.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
 ```
@@ -45,6 +45,21 @@ Each is a root script for the `mfeflow` CLI in your devDependencies (`pnpm mfefl
 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.
 
+## Deploy it
+
+```sh
+pnpm build
+pnpm mfeflow deploy catalog --env staging --host file:./site --base-url https://cdn.example.com
+pnpm mfeflow promote catalog --from staging --to prod --host file:./site
+pnpm mfeflow rollback catalog --env prod --host file:./site
+pnpm mfeflow status --host file:./site
+```
+
+`deploy` uploads a remote's `dist` and points an environment at it, `rollback` points it back without a rebuild, and
+`status` shows what is served. Put `host` and `baseUrl` under `registry` in `mfeflow.json` to drop the flags, or use
+`s3://<bucket>` with the `MFEFLOW_S3_*` and `AWS_*` variables. There are no root scripts for these, because the package manager has a deploy command of its own, so
+run them through `pnpm mfeflow`.
+
 ## Before you deploy
 
 `registry/envs/staging` and `registry/envs/prod` point at `example.com`. Replace the hosts

package/assets/templates/monorepo/files/shell/{mfe.json.eta → mfeflow.app.json.eta}

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://mfeflow.github.io/mfeflow/schema/mfeflow-app.json",
   "name": "<%= it.app.name %>",
   "owner": "team-<%= it.app.name %>",
   "shells": [],

package/assets/templates/monorepo/files/shell/rsbuild.config.ts.eta

@@ -3,7 +3,40 @@ import path from 'node:path';
 import { defineConfig, mergeRsbuildConfig } from '@rsbuild/core';
 import { createShellConfig } from '@mfeflow/rsbuild';
 
-interface DevEntry {
+<% if (it.topology === 'polyrepo') { %>interface DevRemote {
+  name: string;
+  entry: string;
+  version: string;
+}
+
+function readDevRemotes(file: string): DevRemote[] {
+  let value: unknown;
+  try {
+    value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    // A shell with no dev config yet has no remotes to list.
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return [];
+    throw error;
+  }
+  const remotes =
+    typeof value === 'object' && value !== null && 'devRemotes' in value ? value.devRemotes : {};
+  if (typeof remotes !== 'object' || remotes === null) {
+    throw new Error(`${file}: devRemotes must be an object of name: manifest URL`);
+  }
+  return Object.entries(remotes)
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .map(([name, entry]) => {
+      if (typeof entry !== 'string') throw new Error(`${file}: devRemotes.${name} must be a URL`);
+      return { name, entry, version: 'dev' };
+    });
+}
+
+// The shell finds its remotes through the registry. The remotes live in other repos, so in dev
+// their manifest URLs come from "devRemotes" in public/config/runtime-config.dev.json, inlined so
+// the shell needs no registry server. `mfeflow dev` writes the merged registry (that file, plus
+// --remote overrides) to MFEFLOW_DEV_REGISTRY; plain `pnpm dev` reads the file.
+const devConfig = path.resolve(process.cwd(), 'public/config/runtime-config.dev.json');
+<% } else { %>interface DevEntry {
   manifestUrl: string;
   version: string;
 }
@@ -34,7 +67,7 @@ function readNames(dir: string): string[] {
 // `mfeflow dev` writes the merged registry (apps from mfeflow.json, --remote overrides) to
 // MFEFLOW_DEV_REGISTRY and rewrites it when the project changes; plain `pnpm dev` reads the folder.
 const registryDir = path.resolve(process.cwd(), '../../registry/envs/dev');
-const generated = process.env.MFEFLOW_DEV_REGISTRY;
+<% } %>const generated = process.env.MFEFLOW_DEV_REGISTRY;
 
 function readGenerated(file: string): unknown {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -44,7 +77,9 @@ function devRegistry(): string {
   const remotes = generated
     ? readGenerated(generated)
     : {
-        remotes: readNames(registryDir)
+<% if (it.topology === 'polyrepo') { %>        remotes: readDevRemotes(devConfig),
+      };
+<% } else { %>        remotes: readNames(registryDir)
           .filter((file) => file.endsWith('.json'))
           .toSorted()
           .map((file) => {
@@ -52,7 +87,7 @@ function devRegistry(): string {
             return { name: file.slice(0, -'.json'.length), entry: manifestUrl, version };
           }),
       };
-  return `window.__MFE_REGISTRY__=${JSON.stringify(remotes).replaceAll('<', '\\u003c')}`;
+<% } %>  return `window.__MFE_REGISTRY__=${JSON.stringify(remotes).replaceAll('<', '\\u003c')}`;
 }
 
 export default defineConfig(({ command }) =>
@@ -61,8 +96,9 @@ export default defineConfig(({ command }) =>
     createShellConfig({ name: '<%= it.app.name %>', port: <%= it.app.port %>, snapshot: true }),
     defineConfig({
       // A new or changed remote restarts the dev server, which reads the registry again.
-      dev: { watchFiles: { paths: generated ?? registryDir, type: 'restart' } },
-      html: {
+<% if (it.topology === 'polyrepo') { %>      dev: { watchFiles: { paths: generated ?? devConfig, type: 'restart' } },
+<% } else { %>      dev: { watchFiles: { paths: generated ?? registryDir, type: 'restart' } },
+<% } %>      html: {
         title: '<%= it.app.name %>',
         tags:
           command === 'dev'

package/assets/templates/monorepo/files/shell/src/assert.ts.eta

@@ -0,0 +1,37 @@
+/* oxlint-disable eslint/no-underscore-dangle -- __MFEFLOW_SINGLETONS__ is the name the rsbuild preset defines */
+import { checkSingletons, reportRemoteError } from '@mfeflow/runtime';
+
+// The shell's rsbuild preset defines the packages it shares; an older preset does not, so fall back.
+declare const __MFEFLOW_SINGLETONS__: readonly string[] | undefined;
+const SINGLETONS =
+  typeof __MFEFLOW_SINGLETONS__ === 'undefined' ? ['react', 'react-dom'] : __MFEFLOW_SINGLETONS__;
+
+// Remotes register their shared packages as they load, so the check repeats for a while.
+const CHECK_EVERY_MS = 3000;
+const STOP_AFTER_MS = 60_000;
+
+declare global {
+  var mfeflowCheckSingletons: (() => ReturnType<typeof checkSingletons>) | undefined;
+}
+
+const reported = new Set<string>();
+
+function check(): ReturnType<typeof checkSingletons> {
+  const result = checkSingletons(SINGLETONS);
+  // `missing` is not a problem: a shared package nothing has loaded yet is not in the share scope.
+  for (const name of result.duplicated) {
+    const problem = `${name} is loaded in more than one version`;
+    if (reported.has(problem)) continue;
+    reported.add(problem);
+    reportRemoteError('<%= it.app.name %>', 'singletons', new Error(problem));
+  }
+  return result;
+}
+
+// Loaded only in development: it reads every loaded remote's share scope.
+globalThis.mfeflowCheckSingletons = check;
+check();
+const timer = setInterval(check, CHECK_EVERY_MS);
+setTimeout(() => {
+  clearInterval(timer);
+}, STOP_AFTER_MS);

package/assets/templates/monorepo/files/shell/src/bootstrap.tsx.eta

@@ -3,6 +3,7 @@ import {
   applyDevOverrides,
   loadRegistryIndex,
   registerRemotesFromIndex,
+  registrySources,
   reportRemoteError,
 } from '@mfeflow/runtime';
 import { App } from './App';
@@ -12,13 +13,22 @@ const DEV = process.env.NODE_ENV !== 'production';
 export async function main(): Promise<void> {
   try {
     // Dev only: ?mfe-override=cart@http://localhost:4312/mf-manifest.json points a remote at your build.
-    const index = applyDevOverrides(await loadRegistryIndex(), { enabled: DEV });
+    // runtime-config.json can set registryUrls (primary, then fallback) and registryOrigins for a CDN-hosted registry;
+    // it never holds up boot for more than 1.5 s, and is not fetched at all when the index is inlined.
+    const { urls, allowedOrigins: cdnOrigins } = await registrySources();
+    const index = applyDevOverrides(await loadRegistryIndex(urls, { allowedOrigins: cdnOrigins }), {
+      enabled: DEV,
+    });
     // In dev the registry points at the remotes' dev servers; elsewhere remotes share the shell's origin.
     const devOrigins = DEV ? index.remotes.map((remote) => new URL(remote.entry).origin) : [];
-    registerRemotesFromIndex(index, { allowedOrigins: [location.origin, ...devOrigins] });
+    registerRemotesFromIndex(index, {
+      allowedOrigins: [location.origin, ...cdnOrigins, ...devOrigins],
+    });
   } catch (error) {
     reportRemoteError('<%= it.app.name %>', 'registry', error);
   }
   const el = document.getElementById('root');
   if (el) createRoot(el).render(<App />);
+  // Development only, so production builds carry nothing for it.
+  if (DEV) void import('./assert');
 }

package/assets/templates/monorepo/migrations/0.4.0-app-file.mjs

@@ -0,0 +1,58 @@
+// core 0.4.0: each app's ownership file is now mfeflow.app.json, not mfe.json.
+// Moves the content of every app's mfe.json to mfeflow.app.json, with the schema URL updated,
+// and deletes mfe.json. An app that already has both files is left alone with a warning (E122).
+// Self-contained on purpose: `mfeflow upgrade` imports it from the feature folder.
+
+const OLD = 'mfe.json';
+const NEW = 'mfeflow.app.json';
+const OLD_SCHEMA = 'https://mfeflow.github.io/mfeflow/schema/mfe.json';
+const NEW_SCHEMA = 'https://mfeflow.github.io/mfeflow/schema/mfeflow-app.json';
+
+const inApp = (dir, file) => (dir === '' ? file : `${dir}/${file}`);
+
+/** The file text with the new schema URL: the old URL replaced, or a `$schema` line added first. */
+export function withNewSchema(text) {
+  if (text.includes(OLD_SCHEMA)) return text.replaceAll(OLD_SCHEMA, NEW_SCHEMA);
+  if (text.includes('"$schema"')) return text;
+  const open = /^\{(\r?\n)/.exec(text);
+  if (!open) return text;
+  return `{${open[1]}  "$schema": "${NEW_SCHEMA}",${open[1]}${text.slice(open[0].length)}`;
+}
+
+/**
+ * @param {import('@mfeflow/core').PlanBuilder} builder
+ * @param {import('@mfeflow/core').MfeflowProject} project
+ */
+export default async function migrate(builder, project) {
+  const dirs = Object.values(project.apps)
+    .map((app) => app.path)
+    .toSorted();
+  for (const dir of dirs) {
+    const from = inApp(dir, OLD);
+    const to = inApp(dir, NEW);
+    // oxlint-disable-next-line no-await-in-loop -- apps in order keep the plan deterministic
+    const text = await builder.content(from);
+    if (text === undefined) continue;
+    // oxlint-disable-next-line no-await-in-loop -- see above
+    if (await builder.existed(to)) {
+      builder.warn(
+        `${dir || '.'} has both ${OLD} and ${NEW}; keep ${NEW} and delete ${OLD} (E122)`,
+      );
+      continue;
+    }
+    const moved = withNewSchema(text);
+    // The upgrade may already plan a fresh NEW file from the template. When the old file was
+    // never edited the two match and that tracked file stays. Otherwise your content wins, and
+    // it is not tracked, so a later upgrade shows a diff instead of replacing it.
+    // oxlint-disable-next-line no-await-in-loop -- see above
+    const planned = await builder.content(to);
+    if (planned !== moved) {
+      // oxlint-disable-next-line no-await-in-loop -- see above
+      if (planned !== undefined) await builder.delete(to);
+      // oxlint-disable-next-line no-await-in-loop -- see above
+      await builder.create(to, moved, false);
+    }
+    // oxlint-disable-next-line no-await-in-loop -- see above
+    await builder.delete(from);
+  }
+}

package/assets/templates/polyrepo/feature.json

@@ -0,0 +1,305 @@
+{
+  "name": "polyrepo",
+  "version": "0.2.0",
+  "description": "What a polyrepo repo has beyond the monorepo template: the platform packages, the reusable CI and Renovate preset, and a package.json, README and CI caller for each repo.",
+  "prompts": [
+    {
+      "name": "repo",
+      "type": "select",
+      "message": "Which repo of the polyrepo this is",
+      "choices": ["platform", "shell", "remote"],
+      "default": "platform"
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "message": "The remote's name (repo remote only)",
+      "default": ""
+    },
+    {
+      "name": "org",
+      "type": "string",
+      "message": "The GitHub owner the repos will live under (default: the scope without @)",
+      "default": ""
+    }
+  ],
+  "files": [
+    {
+      "to": "AGENTS.md",
+      "target": "root",
+      "from": "files/AGENTS.md.eta",
+      "template": true
+    },
+    {
+      "to": "renovate.json",
+      "target": "root",
+      "from": "files/renovate.json.eta",
+      "template": true
+    },
+    {
+      "to": "README.md",
+      "target": "root",
+      "from": "files/platform/README.md.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "README.md",
+      "target": "root",
+      "from": "files/shell/README.md.eta",
+      "template": true,
+      "when": {
+        "repo": "shell"
+      }
+    },
+    {
+      "to": "README.md",
+      "target": "root",
+      "from": "files/remote/README.md.eta",
+      "template": true,
+      "when": {
+        "repo": "remote"
+      }
+    },
+    {
+      "to": "default.json",
+      "target": "root",
+      "from": "files/platform/default.json.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "tsconfig.base.json",
+      "target": "root",
+      "from": "files/tsconfig.base.json.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "packages/contracts/package.json",
+      "target": "root",
+      "from": "files/packages/contracts/package.json.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "packages/contracts/tsconfig.json",
+      "target": "root",
+      "from": "files/packages/contracts/tsconfig.json.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "packages/contracts/src/index.ts",
+      "target": "root",
+      "from": "files/packages/contracts/src/index.ts",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "packages/tokens/package.json",
+      "target": "root",
+      "from": "files/packages/tokens/package.json.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "packages/tokens/tsconfig.json",
+      "target": "root",
+      "from": "files/packages/tokens/tsconfig.json.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": "packages/tokens/src/index.ts",
+      "target": "root",
+      "from": "files/packages/tokens/src/index.ts",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": ".changeset/config.json",
+      "target": "root",
+      "from": "files/changeset/config.json",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": ".changeset/README.md",
+      "target": "root",
+      "from": "files/changeset/README.md",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": ".github/workflows/ci.yml",
+      "target": "root",
+      "from": "files/workflows/platform-ci.yml",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": ".github/workflows/reusable-ci.yml",
+      "target": "root",
+      "from": "files/workflows/reusable-ci.yml.eta",
+      "template": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": ".github/workflows/release.yml",
+      "target": "root",
+      "from": "files/workflows/release.yml",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "to": ".github/workflows/ci.yml",
+      "target": "root",
+      "from": "files/workflows/team-ci.yml.eta",
+      "template": true,
+      "when": {
+        "repo": "shell"
+      }
+    },
+    {
+      "to": ".github/workflows/ci.yml",
+      "target": "root",
+      "from": "files/workflows/team-ci.yml.eta",
+      "template": true,
+      "when": {
+        "repo": "remote"
+      }
+    },
+    {
+      "to": "public/config/runtime-config.staging.json",
+      "target": "shell",
+      "content": "{\n  \"environment\": \"staging\"\n}\n"
+    },
+    {
+      "to": "public/config/runtime-config.prod.json",
+      "target": "shell",
+      "content": "{\n  \"environment\": \"prod\"\n}\n"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@changesets/cli",
+      "range": "3.0.3",
+      "target": "root",
+      "dev": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "typescript",
+      "range": "7.0.2",
+      "target": "root",
+      "dev": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "mfeflow",
+      "range": "latest",
+      "target": "root",
+      "dev": true,
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "{{scope}}/tokens",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "latest",
+      "target": "remotes"
+    },
+    {
+      "name": "{{scope}}/tokens",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ],
+  "scripts": [
+    {
+      "name": "build",
+      "command": "pnpm -r --if-present run build",
+      "target": "root",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "typecheck",
+      "command": "pnpm -r --if-present run typecheck",
+      "target": "root",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "validate",
+      "command": "mfeflow validate",
+      "target": "root",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "changeset",
+      "command": "changeset",
+      "target": "root",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "version",
+      "command": "changeset version",
+      "target": "root",
+      "when": {
+        "repo": "platform"
+      }
+    },
+    {
+      "name": "release",
+      "command": "pnpm build && changeset publish",
+      "target": "root",
+      "when": {
+        "repo": "platform"
+      }
+    }
+  ]
+}

package/assets/templates/polyrepo/files/AGENTS.md.eta

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repo.
+
+- This is the <%= it.options.repo %> repo of a polyrepo. The other repos are its siblings: `../platform`, `../shell` and one per team.
+- 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:`.
+<% if (it.options.repo === 'platform') { %>- Every change to a package in `packages/` needs a changeset (`pnpm changeset`).
+- Never import from a sibling repo by path. Other repos depend on what is published from here.
+<% } else { %>- `<%= it.scope %>/*` packages come from `../platform` (`link:` paths until they are published). Build the platform repo first.
+- TypeScript 7, strict. Relative imports have no file extension (`./plan`, not `./plan.js`).
+- Add features with the `mfeflow` CLI (`pnpm mfeflow add <feature>`). `mfeflow.json` is its record of this repo.
+<% } %><% if (it.options.repo === 'remote') { %>- A remote's public surface is `src/exposed/`. It must not import from the shell or another remote.
+<% } %><% if (it.options.repo === 'shell') { %>- A new remote gets a repo with `pnpm mfeflow add team-repo <name>`. Do not add remotes to this repo by hand.
+<% } %>EOF

package/assets/templates/polyrepo/files/changeset/README.md

@@ -0,0 +1,5 @@
+# Changesets
+
+Run `pnpm changeset` in any pull request that changes a package here. Pick the bump and describe
+the change for the teams that use it. When the pull request merges, the release workflow opens a
+"chore: version packages" pull request. Merging that one publishes the packages.

package/assets/templates/polyrepo/files/changeset/config.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/assets/templates/polyrepo/files/packages/contracts/package.json.eta

@@ -0,0 +1,23 @@
+{
+  "name": "<%= it.scope %>/contracts",
+  "version": "0.1.0",
+  "description": "Event names and types the shell and every remote agree on.",
+  "type": "module",
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "catalog:"
+  }
+}