mfeflow 0.4.0 → 0.6.0

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"
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+# <%= it.scope.slice(1) %>-<%= it.options.name %>
+
+A remote of a polyrepo made with [mfeflow](https://github.com/mfeflow/mfeflow). It exposes `./App`
+and is deployed on its own. The shell lives in its own repo.
+
+```
+apps/<%= it.options.name %>   the remote
+```
+
+## Run it
+
+```sh
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` serves the remote on its own port. To see it inside the shell, run `pnpm dev` in the shell
+repo too: the shell's dev config lists this remote's dev server.
+
+## Deploy it
+
+Each remote is deployed on its own. The registry entries live in the shell repo, not here. See
+"Deploy and roll back" in the mfeflow docs for the commands.

package/assets/templates/polyrepo/files/renovate.json.eta

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github><%= it.options.org || it.scope.slice(1) %>/platform"]
+}

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

@@ -0,0 +1,32 @@
+# <%= it.scope.slice(1) %>-shell
+
+The shell of a polyrepo made with [mfeflow](https://github.com/mfeflow/mfeflow): routes, layout and
+the registry that tells it which build of each remote to load. The remotes are in their own repos.
+
+```
+apps/shell                                  the host
+apps/shell/public/config/runtime-config.*   per environment; dev lists where the remotes run
+registry/envs                               which build of each remote staging and prod serve
+```
+
+## Run it
+
+```sh
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` starts the shell on http://localhost:4300. It finds each remote in `devRemotes` in
+`apps/shell/public/config/runtime-config.dev.json`. Start a remote with `pnpm dev` in its own repo.
+
+`pnpm mfeflow dev` runs the shell the same way and reloads the list when that file changes.
+Point one remote somewhere else for a run with `pnpm mfeflow dev --remote cart=http://localhost:3001`.
+
+## Add a team repo
+
+```sh
+pnpm mfeflow add team-repo checkout
+```
+
+This creates `../checkout` as a new git repo and registers it here. Run `git init` and the GitHub
+steps yourself.

package/assets/templates/polyrepo/files/tsconfig.base.json.eta

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "skipLibCheck": true,
+    "types": []
+  }
+}

package/assets/templates/polyrepo/files/workflows/platform-ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  pull_request:
+
+permissions: {}
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: lts/*
+          cache: pnpm
+      - run: pnpm install
+      - run: pnpm build
+      - run: pnpm mfeflow validate

package/assets/templates/polyrepo/files/workflows/release.yml

@@ -0,0 +1,40 @@
+name: release
+
+# Publishes the packages in packages/ when a "chore: version packages" pull request is merged.
+# Set the NPM_TOKEN secret for npm, or change the registry in .npmrc for GitHub Packages.
+# Dormant until the repository variable RELEASE_ENABLED is 'true'.
+on:
+  push:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: vars.RELEASE_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: lts/*
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install
+      - uses: changesets/action@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2.1.2
+        with:
+          publish: pnpm release
+          pr-title: 'chore: version packages'
+          commit-message: 'chore: version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/assets/templates/polyrepo/files/workflows/reusable-ci.yml.eta

@@ -0,0 +1,50 @@
+name: reusable-ci
+
+# Every team repo calls this file from its own workflow:
+#
+#   jobs:
+#     ci:
+#       uses: <%= it.options.org || it.scope.slice(1) %>/platform/.github/workflows/reusable-ci.yml@main
+#
+# A private platform repo has to allow it under Settings > Actions > General > Access.
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        description: Node version to run the checks on
+        type: string
+        default: lts/*
+      run-budget:
+        description: Also run mfeflow budget after the build
+        type: boolean
+        default: false
+
+permissions: {}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: pnpm
+      - run: pnpm install
+      - run: pnpm run --if-present typecheck
+      - run: pnpm run --if-present lint
+      - run: pnpm run --if-present test
+      - run: pnpm build
+      - name: mfeflow validate
+        run: pnpm mfeflow validate
+      - name: mfeflow doctor
+        run: pnpm mfeflow doctor
+      - name: mfeflow budget
+        if: ${{ inputs.run-budget }}
+        run: pnpm mfeflow budget

package/assets/templates/polyrepo/files/workflows/team-ci.yml.eta

@@ -0,0 +1,12 @@
+name: ci
+
+on:
+  pull_request:
+
+permissions: {}
+
+jobs:
+  ci:
+    permissions:
+      contents: read
+    uses: <%= it.options.org || it.scope.slice(1) %>/platform/.github/workflows/reusable-ci.yml@main

package/dist/against.d.ts

@@ -0,0 +1,16 @@
+import { type FetchLike } from '@mfeflow/core';
+/** The shell a remote is checked against, as its deployed `mf-manifest.json`. */
+export interface ShellSource {
+    /** What the user passed, for the report. */
+    from: string;
+    manifest: unknown;
+}
+/**
+ * The shell's `mf-manifest.json` from `source`: the manifest itself, or a registry index, whose
+ * `shell/mf-manifest.json` is read from beside it. `source` is a file or an https URL (http on
+ * localhost). Fails with E307 on anything else.
+ */
+export declare function loadShell(source: string, options: {
+    cwd: string;
+    fetch: FetchLike;
+}): Promise<ShellSource>;

package/dist/catalog.d.ts

@@ -13,12 +13,20 @@ export declare function isFirstParty(name: string): boolean;
 /** The first-party features a user may pick, in catalogue order. */
 export declare const OPTIONAL_FEATURES: readonly string[];
 export declare const DEFAULT_FEATURES: readonly string[];
+/** `polyrepo` is applied by `init --topology polyrepo`; it is not offered by `add` or listed by `features`. */
+export declare const POLYREPO_FEATURE = "polyrepo";
 export interface FeatureSource {
     roots: AssetRoots;
     registries?: Record<string, string> | undefined;
     fetch?: FetchLike | undefined;
     /** The version to ask a registry for, when its URL template can pin one. */
     version?: string | undefined;
+    /** Namespaces the user trusts, so their registries may be on loopback or private addresses. */
+    trusted?: ReadonlySet<string> | undefined;
+    /** Compare the registry index's version with the feature.json's. */
+    checkIndex?: boolean | undefined;
 }
 /** A first-party feature by name, or `@namespace/name` from a configured registry. */
 export declare function loadAny(name: string, source: FeatureSource): Promise<LoadedFeature>;
+/** First-party features in the order `init` applies them, then the rest as typed: a feature may edit another's files. */
+export declare function inCatalogueOrder(names: readonly string[]): string[];

package/dist/checks/compat.d.ts

@@ -1,2 +1,14 @@
 import { type Check } from '../findings.js';
+/** Where the shell's versions come from when it is not in this repo. */
+export interface AgainstShell {
+    from: string;
+    manifest: unknown;
+}
+export declare const ABSENT_SHELL_WARNING = "shell is not in this repo, pass --against <url|file>";
+/**
+ * Each remote's shared ranges against the shell. The shell comes from `against` (a deployed
+ * manifest) when given, else from the shells in this repo; with neither, the check warns
+ * instead of passing.
+ */
+export declare function compatCheck(against?: AgainstShell, under?: 'check-compat' | 'doctor'): Check;
 export declare const compat: Check;

package/dist/checks/index.d.ts

@@ -1,6 +1,5 @@
 import type { Check } from '../findings.js';
 /** What `mfeflow validate` runs: the files against their schemas and each other. */
 export declare const VALIDATE_CHECKS: readonly Check[];
-export declare const COMPAT_CHECKS: readonly Check[];
 /** Every check `mfeflow doctor` runs, in order. */
 export declare const DOCTOR_CHECKS: readonly Check[];

package/dist/checks/singletons.d.ts

@@ -1,9 +1,6 @@
+import { comparable } from '@mfeflow/registry/static';
 import { type Check, type Finding } from '../findings.js';
-/**
- * The comparable version behind an installed version or a declared range. Undefined for a spec
- * that names no version (`link:`, `workspace:*`, `catalog:`, `latest`): it is only known after install.
- */
-export declare function comparable(version: string): string | undefined;
+export { comparable };
 /** The warning for specs that cannot be compared before install. */
 export declare function unresolved(check: string, code: 'E301' | 'E302', name: string, specs: readonly string[]): Finding;
 export declare const singletonVersions: Check;

package/dist/commands/add.d.ts

@@ -78,7 +78,9 @@ export declare const ADD_ARGS: {
         readonly description: 'add env-key: root, every shell or every remote, instead of --app';
         readonly valueHint: 'root|shell|remotes';
     };
+    readonly 'accept-changed-content': {
+        readonly type: 'boolean';
+        readonly description: 'Take a registry feature whose content differs from the hash recorded in mfeflow.json';
+    };
 };
-/** First-party features in the order `init` applies them, then the rest as typed: a feature may edit another's files. */
-export declare function inCatalogueOrder(names: readonly string[]): string[];
 export declare function runAdd(rt: Runtime, args: Record<string, unknown>, raw: readonly string[]): Promise<AddResult>;

package/dist/commands/adopt.d.ts

@@ -0,0 +1,54 @@
+import { type Plan } from '@mfeflow/core';
+import { type AdoptResult } from '../output.js';
+import type { Runtime } from '../runtime.js';
+export declare const ADOPT_ARGS: {
+    readonly yes: {
+        readonly type: 'boolean';
+        readonly alias: 'y';
+        readonly description: 'Take the defaults and never prompt';
+    };
+    readonly preset: {
+        readonly type: 'string';
+        readonly description: 'Replay options from a JSON file or an https URL';
+        readonly valueHint: 'file|url';
+    };
+    readonly json: {
+        readonly type: 'boolean';
+        readonly description: 'Print one JSON document on stdout, nothing else';
+    };
+    readonly 'dry-run': {
+        readonly type: 'boolean';
+        readonly description: 'Print the summary and diff, write nothing';
+    };
+    readonly cwd: {
+        readonly type: 'string';
+        readonly description: 'Run as if started in this folder';
+        readonly valueHint: 'dir';
+    };
+    readonly install: {
+        readonly type: 'boolean';
+        readonly default: true;
+        readonly description: 'Run the package manager after writing (--no-install to skip)';
+    };
+    readonly verbose: {
+        readonly type: 'boolean';
+        readonly description: 'Show package manager output and stack traces';
+    };
+    readonly local: {
+        readonly type: 'string';
+        readonly description: 'Link @mfeflow/* from a built mfeflow checkout (env MFEFLOW_LOCAL)';
+        readonly valueHint: 'path';
+    };
+    readonly help: {
+        readonly type: 'boolean';
+        readonly alias: 'h';
+        readonly description: 'Show this help';
+    };
+};
+/** The lines to paste into the shared list of a build config, which adopt never edits. */
+export declare const SHARED_SNIPPET = "    '@mfeflow/runtime': { singleton: true },";
+/** mfeflow.json may have appeared since the first check; the plan would then overwrite it. */
+export declare function assertNoProjectFile(plan: Plan): void;
+/** A last guard behind the promise that adopt never edits a build config. */
+export declare function assertBuildConfigUntouched(plan: Plan, buildConfig: readonly string[]): void;
+export declare function runAdopt(rt: Runtime, args: Record<string, unknown>, raw: readonly string[]): Promise<AdoptResult>;