@multisystemsuite/create-mf-app 1.0.7 → 1.0.9

package/README.md

@@ -16,6 +16,7 @@ Inspired by **Nx**, **Turborepo**, **Backstage**, and **Module Federation** —
 - [Custom child & shared app names](#custom-child--shared-app-names)
 - [Enterprise platform flags](#enterprise-platform-flags)
 - [Generated monorepo structure](#generated-monorepo-structure)
+- [Infrastructure & deployment (parent workspaces)](#infrastructure--deployment-parent-workspaces)
 - [MF Platform CLI (inside generated projects)](#mf-platform-cli-inside-generated-projects)
 - [Using corelib (shared library)](#using-corelib-shared-library)
 - [Enterprise design system & theming](#enterprise-design-system--theming)
@@ -50,6 +51,14 @@ Or use the short binary name (same package):
 npx create-mf-app my-platform --type=parent --children=billing,orders --shared=corelib
 ```
 
+**Contributors:** `npx` installs the **published npm package**. To test unreleased generator changes from this repo, build and run locally — see [Develop & publish this package](#develop--publish-this-package).
+
+```bash
+npm run build
+node dist/index.js my-platform --control-plane -y
+node dist/index.js my-platform --type=parent --children=admin,billing --shared=corelib -y
+```
+
 **Global install** (optional):
 
 ```bash
@@ -270,6 +279,8 @@ npx create-mf-app <project-name> [options]
 | `--shared=corelib` | Shared federated lib folder name (default: `sharedlib`) |
 | `--docker=true\|false` | Generate Dockerfiles (default: `true`) |
 | `--federation=true\|false` | Module Federation (default: `true`) |
+| `--control-plane` | Workflow Designer & Monitoring preset (6 apps + corelib, control-plane API, mf-* packages) |
+| `--federation-os` | Full Enterprise Federation OS preset (10 apps + corelib, runtime, observability stack) |
 | `-y`, `--yes` | Non-interactive (use defaults where applicable) |
 | `-h`, `--help` | Show help |
 
@@ -284,12 +295,16 @@ npx create-mf-app <project-name> [options]
 
 1. Project name  
 2. Application type (parent / child)  
-3. Child applications (checkboxes: admin, qc, inventory, shopfloor)  
-4. Shared applications (comma-separated, default `sharedlib`)  
-5. Template (tsx / jsx)  
-6. Port  
-7. Module Federation on/off  
-8. Docker on/off  
+3. **Parent only:** Workflow Designer & Monitoring (`--control-plane`)?  
+4. **Parent only (if not control-plane):** Full Enterprise Federation OS (`--federation-os`)?  
+5. Child applications — checkbox pick **or auto-filled** when a preset is selected  
+6. Shared applications — comma-separated **or auto-filled** when a preset is selected  
+7. Template (tsx / jsx)  
+8. Port (child mode; presets assign ports from 3000 sequentially)  
+9. Module Federation on/off  
+10. Docker on/off  
+
+**Preset behavior:** choosing `--control-plane` or `--federation-os` skips manual child/shared selection and applies the fixed app list documented below.
 
 ---
 
@@ -341,6 +356,101 @@ Optional modules for **parent monorepos** (core modules are always included):
 | `--testing` | Vitest workspace + Playwright + Cypress configs |
 | `--pwa` | PWA manifest placeholder |
 | `--plugin-system` | Runtime plugin registry in `apps/corelib/src/plugins/` |
+| `--federation-os` | **Full Enterprise Federation OS** — see below |
+| `--control-plane` | **Workflow Designer & Monitoring Platform** — see below |
+
+### Workflow Designer & Monitoring (`--control-plane`)
+
+Focused enterprise control plane matching the Micro Frontend Workflow Designer spec:
+
+```bash
+npx @multisystemsuite/create-mf-app my-control-plane --control-plane -y
+```
+
+| Layer | Generated |
+|-------|-----------|
+| **6 apps + corelib** | shell (`main`), admin, analytics, auth, workflow-monitor-app, federation-registry-app, corelib |
+| **5 packages** | `@scope/shared-ui`, `mf-monitor`, `mf-workflow`, `mf-devtools`, `mf-registry` |
+| **Services** | `services/control-plane-api` (Express + Socket.IO + MongoDB) |
+| **UI** | React Flow designer, real-time monitor, registry, deployments, analytics, environments |
+
+![Enterprise Federation Control Plane — Workflow Designer](docs/images/control-plane-workflow-designer.png)
+
+*Workflow Designer tab at `http://localhost:3004` (or via shell at `/workflow-monitor-app`) — federation topology with live node health, auto-layout, and save/scan controls.*
+
+![Enterprise Federation Control Plane — Federation Monitor](docs/images/control-plane-federation-monitor.png)
+
+*Federation Monitor tab — healthy/unhealthy summary cards and real-time remote health stream (Socket.IO from control-plane API on `:4000`).*
+
+```bash
+npm run control-plane
+npm run mss-mf -- generate workflow
+npm run mss-mf -- generate monitor
+npm run mss-mf -- scan federation
+npm run mss-mf -- add remote analytics-app
+npm run mss-mf -- generate env prod
+```
+
+**Default ports (`--control-plane`):**
+
+| App | Port |
+|-----|------|
+| `main` (shell) | 3000 |
+| `admin-app` | 3001 |
+| `analytics-app` | 3002 |
+| `auth-app` | 3003 |
+| `workflow-monitor-app` | 3004 |
+| `federation-registry-app` | 3005 |
+| `corelib` | 3006 |
+| Control-plane API | 4000 |
+
+### Enterprise Federation OS (`--federation-os`)
+
+One flag scaffolds the complete control plane platform:
+
+```bash
+npx @multisystemsuite/create-mf-app my-federation-platform --federation-os -y
+```
+
+| Layer | Generated |
+|-------|-----------|
+| **10 applications** | Shell (`main`), admin, analytics, auth, workflow-designer, federation-monitor, federation-registry, federation-runtime, federation-governance, deployment-control-plane + `corelib` |
+| **10 packages** | `@scope/mf-runtime`, `mf-monitor`, `mf-workflow`, `mf-registry`, `mf-devtools`, `mf-observability`, `mf-security`, `mf-governance`, `mf-ai-assistant`, `shared-ui` |
+| **Services** | `services/control-plane-api` — Express + Socket.IO + REST (registry, monitor, workflow, deployments, governance, AI) |
+| **Runtime** | `runtime/` — dynamic remote loading + auto-discovery |
+| **Monitoring** | Prometheus + Grafana + OpenTelemetry configs |
+| **Infrastructure** | `docker-compose.federation-os.yml`, Kubernetes manifests, CI pipeline |
+| **Architecture protection** | `.mss-protected.json` + `mss-mf protect` / `delete` guards |
+
+**Federation OS CLI:**
+
+```bash
+npm run control-plane              # API on :4000
+npm run federation-os:infra        # MongoDB, Redis, Postgres, Prometheus, Grafana
+npm run mss-mf -- federation scan  # Auto-discover federation configs
+npm run mss-mf -- federation validate
+npm run mss-mf -- runtime start
+npm run mss-mf -- deploy prod
+```
+
+**Default ports (`--federation-os`):**
+
+| App | Port |
+|-----|------|
+| `main` (shell) | 3000 |
+| `admin-app` | 3001 |
+| `analytics-app` | 3002 |
+| `auth-app` | 3003 |
+| `workflow-designer-app` | 3004 |
+| `federation-monitor-app` | 3005 |
+| `federation-registry-app` | 3006 |
+| `federation-runtime-app` | 3007 |
+| `federation-governance-app` | 3008 |
+| `deployment-control-plane-app` | 3009 |
+| `corelib` | 3010 |
+| Control-plane API | 4000 |
+
+See generated `docs/FEDERATION_OS.md` for full architecture.
 
 **Always included** for federated parent workspaces (no flag needed):
 
@@ -362,6 +472,12 @@ Optional modules for **parent monorepos** (core modules are always included):
 
 ```text
 my-platform/
+├── infrastructure/                  # Auto-generated nginx, apache, docker, k8s, ssl
+│   ├── nginx/nginx.conf
+│   ├── apache/httpd.conf
+│   ├── compose/docker-compose.yml
+│   ├── kubernetes/ingress.yaml
+│   └── scripts/generate-routing.js
 ├── mf.json                          # Workspace config (like nx.json)
 ├── apps/
 │   ├── main/                        # Host shell (port 3000)
@@ -404,6 +520,44 @@ my-platform/
 
 ---
 
+## Infrastructure & deployment (parent workspaces)
+
+Every **parent + federation** workspace auto-generates `infrastructure/` with:
+
+| Path | Contents |
+|------|----------|
+| `infrastructure/nginx/` | `nginx.conf`, federation routing, upstreams, WebSocket, per-env server blocks |
+| `infrastructure/apache/` | `httpd.conf`, federation vhosts, WebSocket proxy |
+| `infrastructure/docker/` | Gateway Dockerfile + per-app production Dockerfiles |
+| `infrastructure/compose/` | `docker-compose.yml` + DEV/QA/UAT/PROD overlays |
+| `infrastructure/kubernetes/` | `deployment.yaml`, `ingress.yaml`, services, HPA |
+| `infrastructure/ssl/` | Self-signed + Certbot scripts, env cert folders |
+| `infrastructure/scripts/` | Auto-routing, remote detection, deploy scripts |
+
+**Deployment modes:**
+
+```bash
+# Container — nginx gateway + all MFE containers
+npm run infra:gateway
+npm run infra:deploy:dev
+npm run infra:deploy:qa
+npm run infra:deploy:uat
+npm run infra:deploy:prod
+
+# Normal server — Vite apps + bare-metal nginx upstreams
+npm run dev
+npm run infra:health
+# use infrastructure/nginx/conf.d/upstreams-bare.conf
+
+# Auto-detect remotes → routing manifest
+npm run infra:detect
+npm run infra:routing
+```
+
+Features: federation-aware reverse proxy, dynamic remote routing (`/remotes/<name>/`), SSL-ready configs, load balancing, health checks, WebSocket for control plane, runtime env injection per environment.
+
+---
+
 ## MF Platform CLI (inside generated projects)
 
 After scaffolding, use the **`mf`** CLI inside your monorepo:
@@ -457,9 +611,37 @@ node tools/mf-cli/bin/mf.js <command>
 | `mf federation doctor` | Check host/remotes/shared lib wiring |
 | `mf federation graph` | Export federation dependency graph |
 | `mf federation sync` | Sync remote manifests from `mf.json` |
-| `mf doctor` | Workspace health (circular deps, boundaries, mf.json) |
+| `mf doctor` | Workspace health (circular deps, boundaries, mf.json, architecture protection) |
 | `npm run federation:verify` | HEAD-check remoteEntry URLs (`MF_REMOTES` env) |
 
+### Architecture protection (`mss-mf`)
+
+Enterprise parent workspaces include `.mss-protected.json` — a guardrail config that prevents accidental deletion or modification of federation OS core infrastructure.
+
+| Tier | Examples | CLI behavior |
+|------|----------|--------------|
+| **Hard protected** | `runtime/`, `tools/mf-cli/`, `governance/`, federation packages | Cannot delete |
+| **Soft protected** | `apps/main`, `apps/corelib`, `plugins/` | Requires `--force` |
+| **Non-critical apps** | Child remotes under `apps/*` | Requires `--force` |
+
+| Command | Description |
+|---------|-------------|
+| `mss-mf delete <path>` | Delete path (blocked if protected) |
+| `mss-mf delete runtime` | ❌ `Cannot delete protected folder: runtime` |
+| `mss-mf delete apps/billing --force` | Remove non-critical child remote |
+| `mss-mf protect validate` | Workspace structure + staged-change validation |
+| `mss-mf protect snapshot` | Capture recovery snapshot in `.mss/snapshots/` |
+| `mss-mf protect recover` | Restore missing paths from latest snapshot |
+| `mss-mf protect list` | List hard/soft protected paths and readonly packages |
+| `mss-mf protect status` | Quick integrity summary |
+
+Git hooks (when `.mss-protected.json` exists):
+
+- **pre-commit** — blocks staged deletion/modification of protected paths
+- **pre-push** — structure validation + dependency integrity
+
+Emergency architect override: `MSS_PROTECT_OVERRIDE=1 mss-mf delete <path> --architect-override`
+
 ### npm script shortcuts (generated)
 
 ```json
@@ -467,7 +649,11 @@ node tools/mf-cli/bin/mf.js <command>
 "mf:graph": "node tools/mf-cli/bin/mf.js graph",
 "mf:affected": "node tools/mf-cli/bin/mf.js affected build",
 "mf:doctor": "node tools/mf-cli/bin/mf.js doctor",
-"mf:federation": "node tools/mf-cli/bin/mf.js federation doctor"
+"mf:federation": "node tools/mf-cli/bin/mf.js federation doctor",
+"mss-mf": "node tools/mf-cli/bin/mf.js",
+"mf:protect": "node tools/mf-cli/bin/mf.js protect validate",
+"mf:protect:snapshot": "node tools/mf-cli/bin/mf.js protect snapshot",
+"mf:protect:recover": "node tools/mf-cli/bin/mf.js protect recover"
 ```
 
 ---
@@ -786,7 +972,9 @@ Husky: lint-staged + type-check + tests on pre-commit; lint + tests on pre-push.
 | `preview:<app>` | Vite preview for one app |
 | `release` / `release:minor` / `release:major` | Version bump + build |
 | `federation:verify` | Remote entry health check |
-| `mf`, `mf:graph`, `mf:affected`, `mf:doctor` | Platform CLI shortcuts |
+| `mf`, `mf:graph`, `mf:affected`, `mf:doctor`, `mss-mf`, `mf:protect` | Platform CLI + architecture protection |
+| `infra:gateway`, `infra:deploy:{dev,qa,uat,prod}`, `infra:detect`, `infra:routing`, `infra:health` | Auto-generated reverse proxy + deployment (parent workspaces) |
+| `control-plane`, `federation-os:infra` | Control-plane API + Federation OS observability stack |
 
 ### Per-module dev (dynamic — one script per `--children` name)
 
@@ -836,6 +1024,8 @@ For container-to-container federation, replace `localhost` remote URLs with Dock
 | `README.md` | Ports, quick start, Docker, quality scripts |
 | `docs/ENTERPRISE_ARCHITECTURE.md` | Design system, RBAC, federation, SDK, deployment |
 | `docs/PLATFORM_ARCHITECTURE.md` | MF CLI, graph, cache, plugins, CI/CD |
+| `docs/CONTROL_PLANE.md` | Workflow designer, monitor, registry (with `--control-plane`) |
+| `docs/FEDERATION_OS.md` | Full Federation OS architecture (with `--federation-os`) |
 | `mf.json` | Project registry, tags, federation config |
 | `templates/README.md` | Template marketplace usage |
 | `ai/README.md` | AI layer integration guide |
@@ -896,11 +1086,18 @@ git clone https://github.com/your-org/create-mf-app
 cd create-mf-app
 npm install
 npm run build          # tsup → dist/
-npm run dev            # run dist/index.js locally
+npm run dev            # run dist/index.js locally (pass args after --)
 
-# test code changes
+# test generator changes locally (uses dist/, not published npm)
+node dist/index.js my-platform --control-plane -y
+node dist/index.js my-platform --type=parent --children=admin,billing --shared=corelib -y
+node dist/index.js my-federation-platform --federation-os -y
 node dist/index.js test-app --type=child --port=3001 --template=tsx
 
+# optional: link CLI globally
+npm link
+create-mf-app my-platform --control-plane -y
+
 # dry-run npm pack contents
 npm run pack:check
 
@@ -920,13 +1117,18 @@ npm publish --access public
 | Layer | How you use it |
 |-------|----------------|
 | **Scaffold** | `npx create-mf-app <name> --type=parent --children=… --shared=corelib` |
+| **Control plane preset** | `--control-plane` → workflow designer, monitor, registry, API |
+| **Federation OS preset** | `--federation-os` → full runtime, governance, observability stack |
 | **Daily dev** | `npm run local` (all apps) or `npm run billing` (one module) |
 | **Shared UI / theme** | Import from `corelib/*` federation exposes |
 | **New remote** | `npm run mf -- generate app <name>` |
 | **Enterprise modules** | Flags: `--auth`, `--charts`, `--i18n`, … |
 | **Monorepo platform** | `mf graph`, `mf affected build`, `mf doctor` |
+| **Architecture protection** | `.mss-protected.json` + `mss-mf protect` / `delete` guards |
+| **Infrastructure** | Auto `infrastructure/` — nginx, docker, k8s, SSL, env deploy scripts |
 | **Federation** | Host :3000 loads remotes; shared React/MUI singletons |
 | **Design system** | `AppConfigProvider` + tokens + runtime theme toggle |
-| **Deploy** | `npm run build` → CDN dist + Helm / Docker |
+| **Deploy** | `npm run build` → CDN dist + `infra:deploy:*` / Helm / Docker |
+| **Local CLI dev** | `npm run build` then `node dist/index.js <name> [flags]` |
 
-**Nx + Turborepo + Module Federation + Backstage + Vite — React-first, enterprise-grade, plugin-driven.**
+**Module Federation + Vite — React-first, enterprise-grade, plugin-driven.**