mfeflow 0.0.0-stage → 0.2.0

package/dist/inspect.d.ts

@@ -0,0 +1,57 @@
+import { type Issue, type MfeManifest, type RegistryEntry } from '@mfeflow/contracts';
+import { type MfeflowProject } from '@mfeflow/core';
+export declare const ENVS: readonly ['dev', 'staging', 'prod'];
+export type Read<T> = {
+    state: 'missing';
+} | {
+    state: 'invalid';
+    issues: Issue[];
+} | {
+    state: 'ok';
+    value: T;
+};
+export interface PackageView {
+    name?: string;
+    version?: string;
+    /** dependencies, devDependencies and peerDependencies, `catalog:` already resolved. */
+    deps: Record<string, string>;
+}
+export interface AppView {
+    name: string;
+    kind: 'shell' | 'remote';
+    /** Path from `mfeflow.json`. */
+    rel: string;
+    dir: string;
+    port: number | undefined;
+    /** The folder has a package.json. */
+    present: boolean;
+    pkg: PackageView | undefined;
+    mfe: Read<MfeManifest>;
+}
+export interface WorkspacePackage {
+    dir: string;
+    rel: string;
+    pkg: PackageView;
+    hasVersion: boolean;
+}
+export interface ProjectView {
+    root: string;
+    project: MfeflowProject;
+    apps: AppView[];
+    workspace: WorkspacePackage[];
+    /** env → remote name → entry. Only remotes with a file in that env are listed. */
+    registry: Record<string, Record<string, Read<RegistryEntry>>>;
+    /** Folders under registry/envs that exist. */
+    envDirs: string[];
+}
+export declare function readText(file: string): Promise<string | undefined>;
+/** Workspace folders for the simple globs pnpm projects use: `dir/*`, plain paths, and `!` exclusions. */
+export declare function expandGlobs(root: string, globs: readonly string[]): Promise<string[]>;
+/** Everything the checks read, loaded once. Throws the E102-E104 errors of `loadProject`. */
+export declare function inspectProject(root: string): Promise<ProjectView>;
+/**
+ * The version of `name` an app uses: what is installed under node_modules (walking up from
+ * the app to the project root, as Node does, never above it), else the version its package.json
+ * declares. Only packages the app declares or the shared list names are looked up.
+ */
+export declare function versionIn(app: Pick<AppView, 'dir' | 'pkg'>, name: string, root: string): Promise<string | undefined>;

package/dist/io.d.ts

@@ -0,0 +1,10 @@
+/** Everything the commands read from or write to the process, so tests can stand in for it. */
+export interface Io {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    cwd: string;
+    env: Readonly<Record<string, string | undefined>>;
+    /** True when both stdin and stdout are terminals, so prompting makes sense. */
+    interactive: boolean;
+}
+export declare function processIo(): Io;

package/dist/local.d.ts

@@ -0,0 +1,28 @@
+import { type MfeflowProject } from '@mfeflow/core';
+/** Range first-party features declare for `@mfeflow/*` packages; the CLI swaps in the real one. */
+export declare const PLACEHOLDER_RANGE = "latest";
+interface LocalPackage {
+    dir: string;
+    built: boolean;
+}
+/** The `@mfeflow/*` packages of a checkout, and the `mfeflow` CLI, by name. */
+export declare function scanCheckout(checkout: string): Map<string, LocalPackage>;
+/**
+ * Turns the placeholder range of an `@mfeflow/*` (or `mfeflow`) dependency into the range the
+ * project should install: `link:<checkout>/packages/<name>` with `--local`, else `^<version>`.
+ */
+export declare function createRangeRewriter(version: string, local?: string): (name: string, range: string) => string | undefined;
+/** `--local none`: stop linking and go back to the published packages. */
+export declare const LOCAL_NONE = "none";
+/**
+ * The checkout a command links `@mfeflow/*` from, and the project recording it. An explicit
+ * `flag` (a path, or `none`) changes the project's mode; without one the project's own mode
+ * stays, so a project is never half linked and half published. Both sides are compared by real
+ * path, so a root and a checkout reached through different symlinks (`/var` -> `/private/var`)
+ * still get the right relative path.
+ */
+export declare function chooseLocal(project: MfeflowProject, root: string, cwd: string, flag: string | undefined): {
+    checkout: string | undefined;
+    project: MfeflowProject;
+};
+export {};

package/dist/options.d.ts

@@ -0,0 +1,7 @@
+export type FeatureOptions = Record<string, Record<string, unknown>>;
+/** `--option feature.key=value` flags as `{ feature: { key: value } }`. `true` and `false` become booleans. */
+export declare function parseFeatureOptions(flags: readonly string[]): FeatureOptions;
+/** `later` wins over `earlier`, key by key. */
+export declare function mergeOptions(earlier: FeatureOptions, later: FeatureOptions): FeatureOptions;
+/** Options for a feature that is not part of this run are a typo or a stale preset, not something to ignore. */
+export declare function assertOptionsAreForFeatures(options: FeatureOptions, features: readonly string[]): void;

package/dist/output.d.ts

@@ -0,0 +1,157 @@
+import type { Issue } from '@mfeflow/contracts';
+import { type Plan } from '@mfeflow/core';
+import { type ErrorReport } from './exit.js';
+import type { Finding } from './findings.js';
+import { type CheckReport, type Summary } from './report.js';
+export interface PlanReport {
+    features: {
+        name: string;
+        version: string;
+    }[];
+    changes: {
+        path: string;
+        action: 'create' | 'patch' | 'delete';
+    }[];
+    dependencies: {
+        file: string;
+        name: string;
+        range: string;
+        dev: boolean;
+    }[];
+    scripts: {
+        file: string;
+        name: string;
+        command: string;
+    }[];
+    warnings: string[];
+}
+export interface AppReport {
+    name: string;
+    kind: 'shell' | 'remote';
+    path: string;
+    port: number | null;
+}
+interface WriteReport {
+    ok: true;
+    dryRun: boolean;
+    root: string;
+    plan: PlanReport;
+    /** Files written, in plan order. Empty for a dry run. */
+    written: string[];
+    installed: boolean;
+    /** Unified diff of every change. Only present for a dry run. */
+    diff?: string;
+}
+export interface InitResult extends WriteReport {
+    command: 'init';
+    scope: string;
+    apps: AppReport[];
+    next: string[];
+}
+export interface AddResult extends WriteReport {
+    command: 'add';
+    kind: 'remote' | 'shell' | 'feature' | 'env-key';
+    /** What was added: an app name, or feature names. */
+    added: string[];
+    /** Features that were already part of the project. */
+    skipped: string[];
+}
+export interface FeatureInfo {
+    name: string;
+    version: string;
+    description: string;
+    always: boolean;
+    default: boolean;
+    installed: boolean;
+}
+export interface FeaturesResult {
+    ok: true;
+    command: 'features';
+    search: string | null;
+    features: FeatureInfo[];
+}
+/** What `doctor`, `validate` and `check-compat` print with `--json`. `ok` is false when any finding is an error. */
+export interface ReportResult {
+    ok: boolean;
+    command: 'doctor' | 'validate' | 'check-compat';
+    root: string;
+    summary: Summary;
+    checks: CheckReport[];
+    findings: Finding[];
+}
+export interface ShellBudget {
+    name: string;
+    /** Gzip KB of the scripts index.html loads. */
+    initialKb: number;
+    scripts: number;
+    /** Your pages built as one app (budget.baselineKb), or null when not set. */
+    baselineKb: number | null;
+    /** baselineKb plus what the shell may add; null without a baseline. */
+    budgetKb: number | null;
+    /** Null when there is nothing to compare with. */
+    pass: boolean | null;
+}
+export interface RouteBudget {
+    route: string;
+    expose: string | null;
+    /** Entry plus the expose's synchronous JS, gzip KB. */
+    kb: number;
+    /** mfe.json budgets.initialJsKb, or null. */
+    budgetKb: number | null;
+    pass: boolean | null;
+}
+export interface RemoteBudget {
+    name: string;
+    entryKb: number;
+    /** What a remote may add (cost model, 10 KB). */
+    budgetKb: number;
+    pass: boolean;
+    routes: RouteBudget[];
+}
+export interface BudgetResult {
+    ok: boolean;
+    command: 'budget';
+    root: string;
+    model: {
+        lcpDeltaMs: number;
+        shellKb: number;
+        remoteKb: number;
+    };
+    shells: ShellBudget[];
+    remotes: RemoteBudget[];
+    findings: Finding[];
+}
+export interface DevApp {
+    name: string;
+    kind: 'shell' | 'remote';
+    port: number | null;
+    url: string | null;
+    command: string;
+    /** `overridden`: a server you run yourself, given with --remote. */
+    status: 'started' | 'overridden';
+}
+export interface DevResult {
+    ok: boolean;
+    command: 'dev';
+    root: string;
+    /** The generated dev registry the shell reads. */
+    registry: string;
+    apps: DevApp[];
+    overrides: Record<string, string>;
+    dryRun: boolean;
+    /** Stopped with Ctrl+C or a termination signal. */
+    interrupted: boolean;
+}
+export interface FailureResult {
+    ok: false;
+    error: ErrorReport;
+    exitCode: number;
+}
+export type CliResult = InitResult | AddResult | FeaturesResult | ReportResult | BudgetResult | DevResult | FailureResult;
+/** The plan as plain data for `--json`, without file contents. Features are listed once. */
+export declare function planReport(plan: Plan): PlanReport;
+/** Checks a document the CLI printed with `--json`. Returns the problems; empty means valid. */
+export declare function validateResult(value: unknown): Issue[];
+/** Exit code for a result that printed normally: findings decide for the checks, Ctrl+C is 130. */
+export declare function exitOf(result: CliResult): number;
+export {};

package/dist/pipeline.d.ts

@@ -0,0 +1,7 @@
+import { PlanBuilder, type MfeflowProject, type Plan } from '@mfeflow/core';
+/** Reads a project file by its `/`-separated path; undefined when it does not exist. */
+export declare function projectReader(root: string): (file: string) => Promise<string | undefined>;
+/** A plan builder that reads `root`, keeps dependency versions in the catalog and resolves `@mfeflow/*` ranges. */
+export declare function createBuilder(root: string, checkout: string | undefined): PlanBuilder;
+/** `plan` with the `mfeflow.json` change added, for the summary and the diff. */
+export declare function withProjectChange(plan: Plan, project: MfeflowProject): Plan;

package/dist/preset.d.ts

@@ -0,0 +1,19 @@
+import { type FetchLike } from '@mfeflow/core';
+/** The options a preset may carry: the same names as the flags of `init`. */
+export interface Preset {
+    scope?: string;
+    remotes?: string[];
+    features?: string[];
+    packageManager?: string;
+    topology?: string;
+    options?: Record<string, Record<string, unknown>>;
+}
+/** Checks a parsed preset. Unknown keys are an error, so a typo does not silently do nothing. */
+export declare function parsePreset(source: string, value: unknown): Preset;
+export interface PresetSources {
+    cwd: string;
+    fetch: FetchLike;
+    readFile?: (file: string) => Promise<string>;
+}
+/** Loads a preset from a file path or an https URL. Plain http is refused. */
+export declare function loadPreset(source: string, sources: PresetSources): Promise<Preset>;

package/dist/proc.d.ts

@@ -0,0 +1,79 @@
+import { type ChildProcess } from 'node:child_process';
+export interface DevProcess {
+    readonly pid: number | undefined;
+    onOutput(listener: (chunk: string) => void): void;
+    onExit(listener: (code: number | null) => void): void;
+    /** Ends the process and everything it started. Resolves once it is gone. */
+    stop(): Promise<void>;
+}
+export interface DevSpec {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+}
+export type SpawnDev = (spec: DevSpec) => DevProcess;
+export interface DevHost {
+    spawn: SpawnDev;
+    /** Calls back on Ctrl+C or a termination signal. Returns a function that stops listening. */
+    onInterrupt(listener: () => void): () => void;
+    /** Calls back, debounced, when any of `paths` changes. Returns a function that stops watching. */
+    watch(paths: readonly string[], listener: () => void): () => void;
+    portFree(port: number): Promise<boolean>;
+    /** How often `dev` looks for a new remote's install to finish, and when it gives up. */
+    waitPolicy?: WaitPolicy;
+}
+export interface WaitPolicy {
+    intervalMs: number;
+    timeoutMs: number;
+}
+export declare const DEFAULT_WAIT: WaitPolicy;
+type Kill = (pid: number, signal: NodeJS.Signals | 0) => void;
+export interface TreeKiller {
+    platform: NodeJS.Platform;
+    kill: Kill;
+    /** Runs `taskkill` on Windows. */
+    taskkill(pid: number): Promise<void>;
+    graceMs: number;
+}
+export interface ResolveEnv {
+    /** The `PATH` value; undefined when the variable is not set. */
+    path: string | undefined;
+    /** Windows: the `PATHEXT` value. */
+    pathext?: string | undefined;
+    platform: NodeJS.Platform;
+    /** Is `file` a runnable file? */
+    isFile(file: string): boolean;
+}
+/**
+ * The absolute path of the first `command` found on the `PATH` entries, in order (on Windows with
+ * each `PATHEXT` extension). A command that has a folder in it is returned as given. Undefined when none is found.
+ */
+export declare function resolveCommand(command: string, env: ResolveEnv): string | undefined;
+/** Stops a process and its children: the process group on POSIX, `taskkill /T` on Windows. */
+export declare function killTree(pid: number, how: TreeKiller): Promise<void>;
+export declare function wrap(child: ChildProcess, killer: TreeKiller): DevProcess;
+export interface ExitSource {
+    on(event: 'exit', listener: () => void): unknown;
+}
+export interface Reaper {
+    track(pid: number): void;
+    untrack(pid: number): void;
+}
+/**
+ * Last resort for dev servers still running when this process exits (a closed terminal, a
+ * crash): kills what is left, synchronously, because nothing async runs inside an `exit` handler.
+ */
+export declare function createReaper(proc: ExitSource, killNow: (pid: number) => void): Reaper;
+export declare const spawnDev: SpawnDev;
+export declare function portFree(port: number): Promise<boolean>;
+/** Watches files (through their folder, since an atomic save replaces the file) and folders. */
+export declare function watchPaths(paths: readonly string[], listener: () => void): () => void;
+export interface SignalSource {
+    on(signal: NodeJS.Signals, listener: () => void): unknown;
+    off(signal: NodeJS.Signals, listener: () => void): unknown;
+}
+/** Ctrl+C, `kill`, and a closed terminal (SIGHUP) all stop the dev servers. */
+export declare function onInterrupt(listener: () => void, source?: SignalSource): () => void;
+export declare function realDevHost(): DevHost;
+export {};

package/dist/prompter.d.ts

@@ -0,0 +1,28 @@
+export interface Choice {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/** The prompts the commands use. The real one is clack; tests pass a scripted one. */
+export interface Prompter {
+    text(options: {
+        message: string;
+        initialValue?: string;
+        validate?: (value: string) => string | undefined;
+    }): Promise<string>;
+    multiselect(options: {
+        message: string;
+        choices: readonly Choice[];
+        initialValues: readonly string[];
+    }): Promise<string[]>;
+    select(options: {
+        message: string;
+        choices: readonly Choice[];
+        initialValue?: string;
+    }): Promise<string>;
+    confirm(options: {
+        message: string;
+        initialValue?: boolean;
+    }): Promise<boolean>;
+}
+export declare const clackPrompter: Prompter;

package/dist/report.d.ts

@@ -0,0 +1,26 @@
+import type { Check, Finding } from './findings.js';
+import type { ProjectView } from './inspect.js';
+export interface CheckReport {
+    id: string;
+    title: string;
+    status: 'pass' | 'warn' | 'fail' | 'skipped';
+    /** Why a skipped check did not run. */
+    skipped?: string;
+    findings: number;
+}
+export interface Summary {
+    errors: number;
+    warnings: number;
+    skipped: number;
+    fixed: number;
+}
+export interface Report {
+    checks: CheckReport[];
+    findings: Finding[];
+}
+export declare function runChecks(view: ProjectView, checks: readonly Check[]): Promise<Report>;
+export declare function summarizeReport(report: Report, fixed: number): Summary;
+/** Exit code of a report: 0 without errors, else the lowest code among the errors' ranges (project before build). */
+export declare function exitForFindings(findings: readonly Finding[]): number;
+/** The human form: one line per check, then each finding with its fix and docs link. */
+export declare function formatReport(report: Report, summary: Summary): string;

package/dist/runtime.d.ts

@@ -0,0 +1,17 @@
+import type { FetchLike } from '@mfeflow/core';
+import { type AssetRoots } from './assets.js';
+import { type Io } from './io.js';
+import { type DevHost } from './proc.js';
+import { type Prompter } from './prompter.js';
+import { type System } from './system.js';
+/** Everything a command touches outside its own arguments. Tests replace the parts they watch. */
+export interface Runtime {
+    io: Io;
+    prompter: Prompter;
+    system: System;
+    fetch: FetchLike;
+    roots: AssetRoots;
+    /** Processes, signals and file watching for `mfeflow dev`. Defaults to the real ones. */
+    dev?: DevHost;
+}
+export declare function realRuntime(io?: Io): Runtime;

package/dist/singletons.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The packages `@mfeflow/rsbuild` shares as singletons, by specifier. A test keeps this equal
+ * to its `DEFAULT_SINGLETONS`; the CLI does not depend on the preset package at run time.
+ */
+export declare const SINGLETON_SPECIFIERS: readonly string[];
+/** `react-dom/client` → `react-dom`, `@mfeflow/theme/react` → `@mfeflow/theme`. */
+export declare function packageNameOf(specifier: string): string;
+/** The singleton packages, each once. */
+export declare const SINGLETON_PACKAGES: readonly string[];
+/** The specifiers of a singleton package, for messages: `react` → react, react/jsx-runtime, … */
+export declare function specifiersOf(name: string): string[];

package/dist/sizes.d.ts

@@ -0,0 +1,17 @@
+export declare const KB = 1024;
+export declare const kb: (bytes: number) => number;
+/** Gzip size at level 6, what a CDN sends. Undefined when the file is not there. */
+export declare function gzipBytes(file: string): Promise<number | undefined>;
+export interface ShellSize {
+    files: string[];
+    bytes: number;
+}
+/** Scripts `dist/index.html` loads, as paths inside dist, and their gzip size. */
+export declare function shellInitial(dist: string): Promise<ShellSize | undefined>;
+export interface RemoteSize {
+    entryBytes: number;
+    /** expose (`./App`) → gzip bytes of the files it loads before it renders, without the entry. */
+    exposes: Record<string, number>;
+}
+/** Entry script and each expose's synchronous JS, read from the remote's `mf-manifest.json`. */
+export declare function remoteSizes(dist: string): Promise<RemoteSize | undefined>;

package/dist/system.d.ts

@@ -0,0 +1,20 @@
+import type { Io } from './io.js';
+export interface RunResult {
+    code: number;
+    output: string;
+}
+/** Runs a program and collects what it prints. Rejects only when it cannot be started. */
+export type Run = (command: string, args: readonly string[], options: {
+    cwd: string;
+    onOutput?: (chunk: string) => void;
+}) => Promise<RunResult>;
+/** `env` without the variables that would bind a child's git to another repository. */
+export declare function isolatedEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const run: Run;
+export interface System {
+    /** Runs `<packageManager> install` in `root`. Throws with the tail of the output when it fails. */
+    install(root: string, packageManager: string, verbose: boolean): Promise<void>;
+    /** `git init` unless `root` is already inside a work tree. Returns whether it ran. */
+    gitInit(root: string): Promise<boolean>;
+}
+export declare function createSystem(io: Pick<Io, 'stderr'>, runner?: Run): System;

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+export interface PackageJson {
+    name: string;
+    version: string;
+}
+/** True when `value` has a string `name` and `version`. */
+export declare function isPackageJson(value: unknown): value is PackageJson;
+/** Name and version from this package's package.json (works from src/ and dist/). */
+export declare function readPackageJson(): PackageJson;

package/dist/write.d.ts

@@ -0,0 +1,26 @@
+import { type MfeflowProject, type Plan } from '@mfeflow/core';
+import type { Globals } from './args.js';
+import type { Runtime } from './runtime.js';
+export interface WriteRequest {
+    rt: Runtime;
+    globals: Globals;
+    root: string;
+    plan: Plan;
+    /** The project as it will be after the plan, saved to `mfeflow.json` in the same transaction. */
+    project: MfeflowProject;
+    /** Runs once the files are written, before the install (`git init` for hooks that need a repo). */
+    afterWrite?: () => Promise<void>;
+}
+export interface WriteOutcome {
+    dryRun: boolean;
+    /** The plan including the `mfeflow.json` change. */
+    shown: Plan;
+    written: string[];
+    installed: boolean;
+    diff?: string;
+}
+/**
+ * Shows the plan and, unless this is a dry run, writes it: all or nothing, with
+ * the install inside the transaction. Backing out at the prompt writes nothing.
+ */
+export declare function writePlan(request: WriteRequest): Promise<WriteOutcome>;

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "mfeflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Create and grow a React micro-frontend platform: mfeflow init, add remote, add <feature>.",
+  "keywords": [
+    "micro-frontend",
+    "micro-frontends",
+    "mfe",
+    "module-federation",
+    "module-federation-2",
+    "react",
+    "rsbuild",
+    "rspack",
+    "cli",
+    "scaffolding",
+    "boilerplate"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "bin": {
+    "mfeflow": "./bin/mfeflow.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "assets",
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "@mfeflow/contracts": "0.2.0",
+    "@mfeflow/core": "0.2.0",
+    "citty": "0.2.2",
+    "semver": "7.8.5",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@mfeflow/rsbuild": "0.2.0",
+    "@rslib/core": "1.0.5",
+    "@types/node": "26.6.6",
+    "@types/semver": "7.8.0",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "node scripts/copy-assets.mjs && rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }