mfeflow 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,7 @@
+packages:
+  - apps/*
+  - packages/*
+
+# Dependencies allowed to run install scripts.
+allowBuilds:
+  lefthook: true

package/assets/templates/monorepo/files/root/turbo.json.eta

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}

package/assets/templates/monorepo/files/shell/mfe.json.eta

@@ -0,0 +1,7 @@
+{
+  "name": "<%= it.app.name %>",
+  "owner": "team-<%= it.app.name %>",
+  "shells": [],
+  "routes": [],
+  "exposes": []
+}

package/assets/templates/monorepo/files/shell/package.json.eta

@@ -0,0 +1,6 @@
+{
+  "name": "<%= it.scope %>/<%= it.app.name %>",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module"
+}

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

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { defineConfig, mergeRsbuildConfig } from '@rsbuild/core';
+import { createShellConfig } from '@mfeflow/rsbuild';
+
+interface DevEntry {
+  manifestUrl: string;
+  version: string;
+}
+
+function readEntry(file: string): DevEntry {
+  const value: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (typeof value !== 'object' || value === null || !('manifestUrl' in value)) {
+    throw new Error(`${file} has no manifestUrl`);
+  }
+  const { manifestUrl } = value;
+  if (typeof manifestUrl !== 'string') throw new Error(`${file}: manifestUrl must be text`);
+  const version = 'version' in value && typeof value.version === 'string' ? value.version : 'dev';
+  return { manifestUrl, version };
+}
+
+function readNames(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir);
+  } catch (error) {
+    // A project with no remotes yet has nothing to list.
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+// The shell finds its remotes through the registry. In dev that is registry/envs/dev, which
+// points at each remote's dev server, inlined so the shell needs no registry server.
+// `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;
+
+function readGenerated(file: string): unknown {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function devRegistry(): string {
+  const remotes = generated
+    ? readGenerated(generated)
+    : {
+        remotes: readNames(registryDir)
+          .filter((file) => file.endsWith('.json'))
+          .toSorted()
+          .map((file) => {
+            const { manifestUrl, version } = readEntry(path.join(registryDir, file));
+            return { name: file.slice(0, -'.json'.length), entry: manifestUrl, version };
+          }),
+      };
+  return `window.__MFE_REGISTRY__=${JSON.stringify(remotes).replaceAll('<', '\\u003c')}`;
+}
+
+export default defineConfig(({ command }) =>
+  mergeRsbuildConfig(
+    // snapshot: registry entries carry a manifest URL until deploys also publish remoteEntry.
+    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: {
+        title: '<%= it.app.name %>',
+        tags:
+          command === 'dev'
+            ? [{ tag: 'script', children: devRegistry(), head: true, append: false }]
+            : [],
+      },
+    }),
+  ),
+);

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

@@ -0,0 +1,46 @@
+import { useEffect, useState, type MouseEvent } from 'react';
+import { DevOverlay } from '@mfeflow/runtime';
+import { routes, type RouteEntry } from './remotes/route-table';
+
+function usePath(): [string, (event: MouseEvent<HTMLAnchorElement>) => void] {
+  const [path, setPath] = useState(location.pathname);
+  useEffect(() => {
+    const onPop = () => {
+      setPath(location.pathname);
+    };
+    addEventListener('popstate', onPop);
+    return () => {
+      removeEventListener('popstate', onPop);
+    };
+  }, []);
+  const go = (event: MouseEvent<HTMLAnchorElement>) => {
+    event.preventDefault();
+    history.pushState(null, '', event.currentTarget.href);
+    setPath(location.pathname);
+  };
+  return [path, go];
+}
+
+const matches = (route: RouteEntry, path: string) =>
+  route.path === '/' ? path === '/' : path === route.path || path.startsWith(`${route.path}/`);
+
+export function App() {
+  const [path, go] = usePath();
+  const current = routes.find((route) => matches(route, path));
+  return (
+    <>
+      <header>
+        <strong><%= it.app.name %></strong>
+        <nav>
+          {routes.map((route) => (
+            <a key={route.path} href={route.path} onClick={go}>
+              {route.path === '/' ? 'home' : route.path.slice(1)}
+            </a>
+          ))}
+        </nav>
+      </header>
+      <main>{current ? <current.Component /> : <p>Nothing at {path}.</p>}</main>
+      <DevOverlay enabled={process.env.NODE_ENV !== 'production'} />
+    </>
+  );
+}

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

@@ -0,0 +1,24 @@
+import { createRoot } from 'react-dom/client';
+import {
+  applyDevOverrides,
+  loadRegistryIndex,
+  registerRemotesFromIndex,
+  reportRemoteError,
+} from '@mfeflow/runtime';
+import { App } from './App';
+
+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 });
+    // 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] });
+  } catch (error) {
+    reportRemoteError('<%= it.app.name %>', 'registry', error);
+  }
+  const el = document.getElementById('root');
+  if (el) createRoot(el).render(<App />);
+}

package/assets/templates/monorepo/files/shell/src/env.d.ts.eta

@@ -0,0 +1 @@
+/// <reference types="@rsbuild/core/types" />

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

@@ -0,0 +1,4 @@
+import { main } from './bootstrap';
+
+// Shared singletons are eager in the shell, so there is no async boundary to wait behind.
+void main();

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

@@ -0,0 +1,12 @@
+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>;
+  return remotes.map((remote) => (
+    <section key={remote.name}>
+      <RemoteBoundary id={`${remote.name}/App`} loading={<p>Loading {remote.name}…</p>} />
+    </section>
+  ));
+}

package/assets/templates/monorepo/files/shell/src/remotes/route-table.tsx.eta

@@ -0,0 +1,12 @@
+import type { ComponentType } from 'react';
+import { Home } from '../pages/Home';
+
+export interface RouteEntry {
+  path: string;
+  Component: ComponentType;
+}
+
+// `mfeflow add remote <name>` adds a route here.
+export const routes: RouteEntry[] = [
+  { path: '/', Component: Home },
+];

package/assets/templates/monorepo/glue/registry-entry.json.eta

@@ -0,0 +1,5 @@
+{
+  "version": "<%= it.version %>",
+  "manifestUrl": "<%= it.manifestUrl %>",
+  "owner": "team-<%= it.name %>"
+}

package/assets/templates/monorepo/glue/route.tsx.eta

@@ -0,0 +1,5 @@
+import { RemoteBoundary } from '@mfeflow/runtime';
+
+export function <%= it.component %>() {
+  return <RemoteBoundary id="<%= it.name %>/App" loading={<p>Loading <%= it.name %>…</p>} />;
+}

package/bin/mfeflow.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../dist/index.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/dist/args.d.ts

@@ -0,0 +1,68 @@
+import type { ArgsDef } from 'citty';
+/** Flags every command takes. */
+export declare const GLOBAL_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';
+    };
+};
+export interface Globals {
+    yes: boolean;
+    preset: string | undefined;
+    json: boolean;
+    dryRun: boolean;
+    cwd: string;
+    install: boolean;
+    verbose: boolean;
+    local: string | undefined;
+    /** A person is at a terminal and has not opted out with --yes or --json. */
+    canPrompt: boolean;
+}
+type Parsed = Record<string, unknown>;
+export declare function text(args: Parsed, key: string): string | undefined;
+export declare function readGlobals(args: Parsed, env: Readonly<Record<string, string | undefined>>, cwd: string, interactive?: boolean): Globals;
+/** Throws E107 for a flag the command does not declare; citty would quietly treat it as a boolean. */
+export declare function assertKnownFlags(raw: readonly string[], defs: ArgsDef): void;
+/** Every value of a repeatable flag (`--option a=1 --option b=2`); citty keeps only the last. */
+export declare function repeated(raw: readonly string[], name: string): string[];
+/** A comma-separated flag or preset value as a list, trimmed, without empties. */
+export declare function splitList(value: string | readonly string[] | undefined): string[] | undefined;
+export {};

package/dist/assets.d.ts

@@ -0,0 +1,13 @@
+export interface AssetRoots {
+    /** Folder with one sub-folder per optional first-party feature. */
+    features: string;
+    /** Folder with the project templates; `monorepo` holds the `core` feature. */
+    templates: string;
+}
+/**
+ * Published, the features and templates are copied next to `dist` (`assets/`).
+ * In a checkout they sit at the repository root, two levels above this package.
+ * Code running from `src` (the tests) always reads the checkout, so an edit to a
+ * template is seen without a build, and a stale `assets/` left by one never is.
+ */
+export declare function assetRoots(from?: string, exists?: (dir: string) => boolean): AssetRoots;

package/dist/catalog.d.ts

@@ -0,0 +1,24 @@
+import { type FetchLike, type LoadedFeature } from '@mfeflow/core';
+import type { AssetRoots } from './assets.js';
+export interface FirstPartyFeature {
+    name: string;
+    /** Part of every project; not offered as a choice. */
+    always: boolean;
+    /** Selected by default in `init`. */
+    default: boolean;
+}
+/** The features that ship with mfeflow, in the order they are applied. */
+export declare const FIRST_PARTY: readonly FirstPartyFeature[];
+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[];
+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;
+}
+/** A first-party feature by name, or `@namespace/name` from a configured registry. */
+export declare function loadAny(name: string, source: FeatureSource): Promise<LoadedFeature>;

package/dist/checks/compat.d.ts

@@ -0,0 +1,2 @@
+import { type Check } from '../findings.js';
+export declare const compat: Check;

package/dist/checks/config.d.ts

@@ -0,0 +1,8 @@
+import { type Check } from '../findings.js';
+export declare const appsOnDisk: Check;
+export declare const mfeJson: Check;
+export declare const ports: Check;
+export declare const routes: Check;
+export declare const registry: Check;
+export declare const localCheckout: Check;
+export declare const drift: Check;

package/dist/checks/env.d.ts

@@ -0,0 +1,6 @@
+import { type Check } from '../findings.js';
+export declare const envExample: Check;
+export declare const runtimeConfig: Check;
+export declare const publicPrefix: Check;
+export declare const turboEnv: Check;
+export declare const envChecks: readonly Check[];

package/dist/checks/index.d.ts

@@ -0,0 +1,6 @@
+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/plugins.d.ts

@@ -0,0 +1,4 @@
+import { type Check } from '../findings.js';
+/** Module specifiers a source file imports, requires or dynamically imports at run time: type-only imports are left out. */
+export declare function importsOf(code: string): string[];
+export declare const runtimePlugins: Check;

package/dist/checks/singletons.d.ts

@@ -0,0 +1,9 @@
+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;
+/** 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/checks/workspace.d.ts

@@ -0,0 +1,2 @@
+import { type Check } from '../findings.js';
+export declare const workspaceVersions: Check;

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+import { type CommandHelp } from './help.js';
+import { type CliResult } from './output.js';
+import { type Runtime } from './runtime.js';
+type Handler = (rt: Runtime, args: Record<string, unknown>, raw: readonly string[]) => Promise<CliResult>;
+interface Command extends CommandHelp {
+    run: Handler;
+}
+export declare const COMMANDS: readonly Command[];
+/** Runs the CLI with `argv` (without node and the script) and returns the exit code. */
+export declare function main(argv: readonly string[], rt?: Runtime): Promise<number>;
+export {};

package/dist/commands/add.d.ts

@@ -0,0 +1,84 @@
+import { type AddResult } from '../output.js';
+import type { Runtime } from '../runtime.js';
+export declare const ADD_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';
+    };
+    readonly port: {
+        readonly type: 'string';
+        readonly description: 'Dev server port for a new app (default: the next free one)';
+        readonly valueHint: 'n';
+    };
+    readonly option: {
+        readonly type: 'string';
+        readonly description: 'A feature option, repeatable: --option feature.key=value';
+        readonly valueHint: 'f.k=v';
+    };
+    readonly scope: {
+        readonly type: 'string';
+        readonly description: 'add env-key: server (env.ts, .env.example) or runtime (runtime-config files)';
+        readonly valueHint: 'server|runtime';
+    };
+    readonly schema: {
+        readonly type: 'string';
+        readonly description: 'add env-key: the validator expression, like "z.url()"';
+        readonly valueHint: 'expr';
+    };
+    readonly value: {
+        readonly type: 'string';
+        readonly description: 'add env-key: the placeholder written to .env.example or the config files';
+        readonly valueHint: 'text';
+    };
+    readonly app: {
+        readonly type: 'string';
+        readonly description: 'add env-key: exactly this app (default: every app; runtime: every shell)';
+        readonly valueHint: 'name';
+    };
+    readonly group: {
+        readonly type: 'string';
+        readonly description: 'add env-key: root, every shell or every remote, instead of --app';
+        readonly valueHint: 'root|shell|remotes';
+    };
+};
+/** 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/budget.d.ts

@@ -0,0 +1,56 @@
+import { type CostModel } from '@mfeflow/contracts';
+import { type ProjectView } from '../inspect.js';
+import type { BudgetResult } from '../output.js';
+import type { Runtime } from '../runtime.js';
+export declare const BUDGET_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';
+    };
+    readonly dist: {
+        readonly type: 'string';
+        readonly description: 'Build output folder inside each app (default dist)';
+        readonly valueHint: 'dir';
+    };
+};
+export declare function modelOf(view: ProjectView): CostModel;
+export declare function runBudget(rt: Runtime, args: Record<string, unknown>, raw: readonly string[]): Promise<BudgetResult>;
+export declare function formatBudget(result: BudgetResult): string;

package/dist/commands/dev.d.ts

@@ -0,0 +1,62 @@
+import type { DevResult } from '../output.js';
+import type { Runtime } from '../runtime.js';
+export declare const DEV_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';
+    };
+    readonly only: {
+        readonly type: 'string';
+        readonly description: 'Run only these apps, comma separated (default: the shell and every remote)';
+        readonly valueHint: 'a,b';
+    };
+    readonly remote: {
+        readonly type: 'string';
+        readonly description: 'Use a server you already run for a remote, repeatable: --remote checkout=http://localhost:3001';
+        readonly valueHint: 'name=url';
+    };
+    readonly 'allow-origin': {
+        readonly type: 'string';
+        readonly description: 'Let --remote point at this origin; localhost is always allowed. Repeatable';
+        readonly valueHint: 'origin';
+    };
+};
+export declare function runDev(rt: Runtime, args: Record<string, unknown>, raw: readonly string[]): Promise<DevResult>;