mfeflow 0.5.0 → 0.7.0

package/assets/templates/monorepo/files/root/pnpm-workspace.yaml.eta

@@ -2,8 +2,9 @@ packages:
   - apps/*
   - packages/*
 
-# Dependencies allowed to run install scripts. esbuild (pulled in by Storybook) works without its
-# script; listing it as false keeps pnpm from stopping the install to ask.
+# Dependencies allowed to run install scripts. esbuild (pulled in by Storybook) and workerd (pulled in
+# by wrangler) work without their script; listing them as false keeps pnpm from stopping the install to ask.
 allowBuilds:
   lefthook: true
   esbuild: false
+  workerd: false

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/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:"
+  }
+}

package/assets/templates/polyrepo/files/packages/contracts/src/index.ts

@@ -0,0 +1,11 @@
+// Names and shapes that more than one repo depends on. A change here is a change for every team,
+// so it goes through a pull request and a changeset like any other published package.
+export const EVENTS = {
+  navigate: 'platform:navigate',
+} as const;
+
+export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
+
+export interface NavigateEvent {
+  path: string;
+}

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

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

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

@@ -0,0 +1,23 @@
+{
+  "name": "<%= it.scope %>/tokens",
+  "version": "0.1.0",
+  "description": "Colors and spacing every team uses.",
+  "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:"
+  }
+}

package/assets/templates/polyrepo/files/packages/tokens/src/index.ts

@@ -0,0 +1,13 @@
+export const colors = {
+  text: '#1b1b1f',
+  surface: '#ffffff',
+  accent: '#3451b2',
+} as const;
+
+export const space = {
+  small: 8,
+  medium: 16,
+  large: 24,
+} as const;
+
+export type Space = keyof typeof space;

package/assets/templates/polyrepo/files/packages/tokens/tsconfig.json.eta

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

package/assets/templates/polyrepo/files/platform/README.md.eta

@@ -0,0 +1,43 @@
+# <%= it.scope.slice(1) %>-platform
+
+The shared repo of a polyrepo made with [mfeflow](https://github.com/mfeflow/mfeflow). The shell and
+every team repo sit next to it and depend on what is published from here.
+
+```
+packages/contracts   <%= it.scope %>/contracts: event names and types every repo agrees on
+packages/tokens      <%= it.scope %>/tokens: colors and spacing
+.github/workflows    reusable-ci.yml (the CI every team repo calls), ci.yml, release.yml
+default.json         the Renovate preset every repo extends
+.changeset           how a change here gets a version
+```
+
+## Run it
+
+```sh
+pnpm install
+pnpm build
+```
+
+Build here first. The shell and the team repos link to `packages/*/dist` until you publish.
+
+## Change a package
+
+```sh
+pnpm changeset          # describe the change and pick the bump
+pnpm build
+```
+
+Commit the changeset with your change. After the pull request merges, the release workflow opens a
+version pull request. Merging that publishes the packages.
+
+## Where the packages are published
+
+The team repos install `<%= it.scope %>/*` with `link:../platform/packages/*` paths so a first run needs
+no registry. To share the packages across machines and CI, publish them to a registry and replace the
+`link:` ranges in each repo with a version:
+
+- npm: set `NPM_TOKEN` as a repository secret. Packages are public.
+- GitHub Packages: add `<%= it.scope %>:registry=https://npm.pkg.github.com` to `.npmrc` in every repo.
+- A private registry: put its URL in `.npmrc` and set `publishConfig.registry` in each package.
+
+Creating the GitHub repos and the registry account is up to you. mfeflow never calls GitHub.

package/assets/templates/polyrepo/files/platform/default.json.eta

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "description": "Renovate preset for every <%= it.options.org || it.scope.slice(1) %> repo. Each repo extends it with github><%= it.options.org || it.scope.slice(1) %>/platform.",
+  "extends": ["config:recommended"],
+  "packageRules": [
+    {
+      "description": "Singletons the shell and every remote must share move in one pull request per repo.",
+      "matchPackageNames": ["react", "react-dom", "@types/react", "@types/react-dom"],
+      "groupName": "react"
+    },
+    {
+      "description": "Module Federation and Rsbuild have to stay on versions that work together.",
+      "matchPackageNames": ["@module-federation/**", "@rsbuild/**"],
+      "groupName": "module federation and rsbuild"
+    },
+    {
+      "description": "mfeflow packages are released together.",
+      "matchPackageNames": ["mfeflow", "@mfeflow/**"],
+      "groupName": "mfeflow"
+    },
+    {
+      "description": "The packages this org publishes from its platform repo.",
+      "matchPackageNames": ["<%= it.scope %>/**"],
+      "groupName": "platform packages"
+    }
+  ]
+}