feat(cli): implement fwiz init command

apps/cli/package.json

@@ -95,12 +95,14 @@
           }
         }
       },
-      "test": {
-        "options": {
-          "passWithNoTests": true
-        }
-      }
+      "test": {}
     }
   },
-  "dependencies": {}
+  "bin": {
+    "fwiz": "./dist/main.js"
+  },
+  "dependencies": {
+    "@federation-wizards/core": "workspace:*",
+    "commander": "^15.0.0"
+  }
 }

apps/cli/src/commands/init.spec.ts

@@ -0,0 +1,28 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { initFwizConfig } from '@federation-wizards/core';
+import { parse as parseYaml } from 'yaml';
+
+describe('fwiz init command', () => {
+  it('creates fwiz.config.yaml with sensible defaults', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'fwiz-cli-init-'));
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({ dependencies: { react: '^19.0.0' } }),
+    );
+
+    const result = initFwizConfig(dir);
+
+    expect(result.created).toBe(true);
+
+    const config = parseYaml(
+      readFileSync(join(dir, 'fwiz.config.yaml'), 'utf8'),
+    ) as { version: string; hosts: unknown[]; remotes: unknown[] };
+
+    expect(config.version).toBe('1');
+    expect(config.hosts.length).toBeGreaterThan(0);
+    expect(config.remotes.length).toBeGreaterThan(0);
+  });
+});

apps/cli/src/commands/init.ts

@@ -0,0 +1,66 @@
+import type { Command } from 'commander';
+
+import { initFwizConfig } from '@federation-wizards/core';
+
+export function registerInitCommand(program: Command): void {
+  program
+    .command('init')
+    .description(
+      'Generate a central fwiz.config.yaml for Module Federation 2.0',
+    )
+    .summary('Scaffold fwiz.config.yaml with workspace-aware defaults')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  $ fwiz init
+  $ fwiz init --cwd ./my-monorepo
+
+The command detects Nx, Turborepo, or plain repositories and creates
+sensible host, remote, and shared dependency defaults. Running init
+again is safe: an existing fwiz.config.yaml is validated but not overwritten.
+`,
+    )
+    .option(
+      '--cwd <path>',
+      'Directory to initialize (defaults to current working directory)',
+      process.cwd(),
+    )
+    .action((options: { cwd: string }) => {
+      const result = initFwizConfig(options.cwd);
+
+      if (result.created) {
+        console.log(`Created ${result.configPath}`);
+        console.log(
+          `Detected ${result.config.workspace.type} workspace with ${result.config.hosts.length} host(s) and ${result.config.remotes.length} remote(s).`,
+        );
+      } else {
+        console.log(`Config already exists at ${result.configPath}`);
+      }
+
+      const patchedFiles = result.workspacePatches.filter(
+        (patch) => patch.patched,
+      );
+
+      for (const patch of patchedFiles) {
+        for (const change of patch.changes) {
+          console.log(change);
+        }
+      }
+
+      if (result.created) {
+        return;
+      }
+
+      if (result.validationWarnings.length > 0) {
+        console.warn('Validation warnings:');
+        for (const warning of result.validationWarnings) {
+          console.warn(`  - ${warning}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log('Existing config is valid.');
+    });
+}

apps/cli/src/main.ts

@@ -1 +1,5 @@
-console.log('Hello World');
+#!/usr/bin/env node
+
+import { createProgram } from './program.js';
+
+createProgram().parse(process.argv);

apps/cli/src/program.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+
+import { registerInitCommand } from './commands/init.js';
+
+export function createProgram(): Command {
+  const program = new Command();
+
+  program
+    .name('fwiz')
+    .description('Federation Wizards CLI for Module Federation workflows')
+    .version('0.0.1');
+
+  registerInitCommand(program);
+
+  return program;
+}

apps/cli/tsconfig.app.json

@@ -17,5 +17,10 @@
     "eslint.config.js",
     "eslint.config.cjs",
     "eslint.config.mjs"
+  ],
+  "references": [
+    {
+      "path": "../../libs/core/tsconfig.lib.json"
+    }
   ]
 }

examples/README.md

@@ -1,3 +1,3 @@
 # Examples
 
-Demo projects will be added here.
+- [`nx-mf-demo`](./nx-mf-demo) — minimal Nx-style Module Federation workspace for `fwiz init` and future dev/validate tests.

examples/nx-mf-demo/README.md

@@ -0,0 +1,18 @@
+# Nx Module Federation Demo
+
+Minimal Nx-style Module Federation workspace used to exercise `fwiz init`, `fwiz dev`, and `fwiz validate` in future work.
+
+## Layout
+
+- `apps/shell` — host application
+- `apps/checkout` — remote application
+
+## Usage
+
+```bash
+cd examples/nx-mf-demo
+pnpm install
+npx fwiz init
+```
+
+`fwiz init` generates `fwiz.config.yaml` and patches `nx.json` with host/remote project references.

examples/nx-mf-demo/apps/checkout/module-federation.config.ts

@@ -0,0 +1,7 @@
+// Placeholder Module Federation 2.0 remote config for fwiz tooling tests.
+export default {
+  name: 'checkout',
+  exposes: {
+    './Checkout': './src/Checkout.tsx',
+  },
+};

examples/nx-mf-demo/apps/checkout/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "checkout",
+  "version": "0.0.0",
+  "private": true,
+  "nx": {
+    "targets": {
+      "serve": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "echo 'checkout dev server placeholder'"
+        }
+      }
+    }
+  }
+}

examples/nx-mf-demo/apps/checkout/project.json

@@ -0,0 +1,7 @@
+{
+  "name": "checkout",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/checkout/src",
+  "projectType": "application",
+  "tags": ["type:remote", "scope:checkout"]
+}

examples/nx-mf-demo/apps/checkout/src/Checkout.tsx

@@ -0,0 +1,3 @@
+export function Checkout() {
+  return <section>Checkout remote placeholder</section>;
+}

examples/nx-mf-demo/apps/shell/module-federation.config.ts

@@ -0,0 +1,5 @@
+// Placeholder Module Federation 2.0 host config for fwiz tooling tests.
+export default {
+  name: 'shell',
+  remotes: ['checkout'],
+};

examples/nx-mf-demo/apps/shell/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "shell",
+  "version": "0.0.0",
+  "private": true,
+  "nx": {
+    "targets": {
+      "serve": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "echo 'shell dev server placeholder'"
+        }
+      }
+    }
+  }
+}

examples/nx-mf-demo/apps/shell/project.json

@@ -0,0 +1,7 @@
+{
+  "name": "shell",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/shell/src",
+  "projectType": "application",
+  "tags": ["type:host", "scope:shell"]
+}

examples/nx-mf-demo/apps/shell/src/main.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+function ShellApp() {
+  return <h1>Shell host placeholder</h1>;
+}
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ShellApp />
+  </React.StrictMode>,
+);

examples/nx-mf-demo/nx.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "../../node_modules/nx/schemas/nx-schema.json",
+  "defaultBase": "main",
+  "workspaceLayout": {
+    "appsDir": "apps",
+    "libsDir": "libs"
+  }
+}

examples/nx-mf-demo/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "nx-mf-demo",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2"
+  }
+}

examples/nx-mf-demo/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "apps/*"

libs/core/package.json

@@ -16,6 +16,8 @@
     }
   },
   "dependencies": {
-    "tslib": "^2.3.0"
+    "joi": "^18.2.1",
+    "tslib": "^2.3.0",
+    "yaml": "^2.9.0"
   }
 }

libs/core/src/index.ts

@@ -1 +1,7 @@
-export * from './lib/core.js';
+export * from './lib/config/types.js';
+export * from './lib/config/schema.js';
+export * from './lib/config/defaults.js';
+export * from './lib/config/init.js';
+export * from './lib/config/load.js';
+export * from './lib/workspace/detect.js';
+export * from './lib/workspace/patch.js';

libs/core/src/lib/config/defaults.ts

@@ -0,0 +1,61 @@
+import type { FwizConfig, WorkspaceInfo } from './types.js';
+
+const DEFAULT_HOST_PORT = 4200;
+const DEFAULT_REMOTE_PORT = 4201;
+
+function createSharedDependencies(reactVersion?: string): FwizConfig['shared'] {
+  const requiredVersion = reactVersion ?? '^19.0.0';
+
+  return {
+    react: {
+      singleton: true,
+      requiredVersion,
+      eager: false,
+    },
+    'react-dom': {
+      singleton: true,
+      requiredVersion,
+      eager: false,
+    },
+  };
+}
+
+function createHosts(appProjects: string[]): FwizConfig['hosts'] {
+  if (appProjects.length === 0) {
+    return [{ name: 'shell', port: DEFAULT_HOST_PORT }];
+  }
+
+  const [hostProject, ..._] = appProjects;
+
+  return [
+    {
+      name: hostProject,
+      project: hostProject,
+      port: DEFAULT_HOST_PORT,
+    },
+  ];
+}
+
+function createRemotes(appProjects: string[]): FwizConfig['remotes'] {
+  if (appProjects.length <= 1) {
+    return [{ name: 'remote', port: DEFAULT_REMOTE_PORT }];
+  }
+
+  return appProjects.slice(1).map((project, index) => ({
+    name: project,
+    project,
+    port: DEFAULT_REMOTE_PORT + index,
+  }));
+}
+
+export function createDefaultConfig(workspace: WorkspaceInfo): FwizConfig {
+  return {
+    version: '1',
+    workspace: {
+      type: workspace.type,
+    },
+    hosts: createHosts(workspace.appProjects),
+    remotes: createRemotes(workspace.appProjects),
+    shared: createSharedDependencies(workspace.reactVersion),
+  };
+}