@mfeflow/contracts 0.0.0-stage → 0.1.0

package/dist/json-schema.d.ts

@@ -0,0 +1,9 @@
+import { type SchemaName } from './docs.js';
+type Json = Record<string, unknown>;
+/**
+ * Editor schemas for the five JSON documents mfeflow reads. They mirror the validators in this package; the
+ * validators stay the authority (they also check things a schema cannot, like duplicate routes), so a document
+ * can pass here and still fail `mfeflow validate`.
+ */
+export declare const JSON_SCHEMAS: Record<SchemaName, Json>;
+export {};

package/dist/manifest-assets.d.ts

@@ -0,0 +1,38 @@
+/** What the registry needs from a built remote's `mf-manifest.json`. */
+export interface RemoteAssets {
+    /** Absolute URL of the remote's entry script. Absent when `manifestOnly` is set. */
+    remoteEntry?: string;
+    /** Per expose (`./App`), URLs of the JS and CSS files it loads before it renders. Empty when `manifestOnly` is set. */
+    exposes: Record<string, string[]>;
+    /**
+     * Why the files' URLs cannot be known at publish time (`metaData.getPublicPath`
+     * computes them in the browser, or a relative `publicPath` resolves against a
+     * page URL that was not given). Keep such a remote manifest-only: publish its
+     * manifest URL, not a `remoteEntry`.
+     */
+    manifestOnly?: string;
+    /** How the entry script is loaded (`module` for ESM). Absent when the manifest does not say. */
+    type?: string;
+    /** The global the entry script defines, when the manifest names one. */
+    entryGlobalName?: string;
+}
+export interface AssetsOptions {
+    /**
+     * The shell page the remote loads into. Module Federation joins a relative or
+     * root-relative `publicPath` as `${publicPath}${file}` and the browser
+     * resolves that against the page, so it is needed to know those URLs here.
+     */
+    pageUrl?: string;
+}
+/**
+ * Reads the entry script and each expose's synchronous files out of a Module
+ * Federation `mf-manifest.json`, resolved against where it is served from
+ * (`manifestUrl`) for an `auto` `publicPath`, and joined to the `publicPath`
+ * otherwise (a relative one against `options.pageUrl`). With
+ * `metaData.getPublicPath`, or a relative `publicPath` and no `pageUrl`, the
+ * URLs cannot be known here: the result has `manifestOnly` set and no
+ * `remoteEntry`. Every URL returned is absolute. Run at
+ * publish or build time; the browser never parses a manifest. Throws on a
+ * manifest without an entry.
+ */
+export declare function assetsFromManifest(manifest: unknown, manifestUrl: string, options?: AssetsOptions): RemoteAssets;

package/dist/mfe-manifest.d.ts

@@ -0,0 +1,42 @@
+import { type Issue } from './validate.js';
+/** `mfe.json`: who owns a micro-frontend and what it promises. */
+export interface MfeManifest {
+    $schema?: string;
+    /** Module Federation name: lowercase letters, digits, `_`. */
+    name: string;
+    /** Owning team, e.g. `team-payments`. Alerts route here. */
+    owner: string;
+    /** Slack channel, email or URL. */
+    contact?: string;
+    /** Shells this remote runs in. Empty for a shell's own manifest. */
+    shells: string[];
+    /** Routes the remote claims, e.g. `/cart` or `/checkout/*`. */
+    routes: string[];
+    /** Exposed modules, e.g. `./App`. */
+    exposes: string[];
+    events?: {
+        publishes: string[];
+        consumes: string[];
+    };
+    analyticsEvents?: string[];
+    budgets?: {
+        initialJsKb?: number;
+        lcpMs?: number;
+    };
+    /** Platform package ranges, e.g. `{ "react": "^19", "@mfeflow/runtime": "^0.2" }`. */
+    platform?: Record<string, string>;
+}
+/**
+ * Lowercase words of letters and digits, joined by single underscores. A name never ends
+ * in `_` and `_` is never followed by a digit, so `cart_` and `cart`, or `a__b` and `a_b`,
+ * cannot become the same component or global name.
+ */
+export declare const MFE_NAME: RegExp;
+export declare const ROUTE: RegExp;
+export declare const EXPOSE: RegExp;
+/** `<domain>.<event>@<major>`, e.g. `cart.item_added@1`. */
+export declare const EVENT_NAME: RegExp;
+/** `<domain>_<object>_<action>`, e.g. `checkout_order_completed`. */
+export declare const ANALYTICS_EVENT: RegExp;
+export declare function validateMfeManifest(value: unknown): Issue[];
+export declare function isMfeManifest(value: unknown): value is MfeManifest;

package/dist/project.d.ts

@@ -0,0 +1,46 @@
+import { type Issue } from './validate.js';
+/** `mfeflow.json`: the CLI's record of a project. */
+export interface MfeflowProject {
+    $schema?: string;
+    version: 1;
+    topology: 'monorepo' | 'polyrepo' | 'hybrid';
+    packageManager: 'pnpm' | 'npm';
+    /** npm scope for the project's own packages, e.g. `@shopco`. */
+    scope: string;
+    apps: Record<string, {
+        kind: 'shell' | 'remote';
+        path: string;
+        port?: number;
+    }>;
+    features: Record<string, {
+        version: string;
+        options?: Record<string, unknown>;
+    }>;
+    /** Hashes of copied files, so `upgrade` can tell when a file was edited. */
+    files?: Record<string, string>;
+    /** Third-party feature registries: `{ "@someone": "https://…/{name}.json" }`. `@mfeflow` is reserved. */
+    registries?: Record<string, string>;
+    /** Built mfeflow checkout, relative to the project root, that `@mfeflow/*` dependencies link to. Set by `--local` only. */
+    local?: string;
+    /** Overrides of the cost-model budget `mfeflow budget` and the perf job check. */
+    budget?: ProjectBudget;
+}
+export interface ProjectBudget {
+    /** JS the shell may add over a one-app build, in KB. Default 32. */
+    shellKb?: number;
+    /** JS each remote on a route may add, in KB. Default 10. */
+    remoteKb?: number;
+    /** LCP the shell may add, in ms. Measured by the perf job, not by `mfeflow budget`. Default 300. */
+    lcpDeltaMs?: number;
+    /** Initial JS of your pages built as one app, in KB. Turns on the shell check in `mfeflow budget`. */
+    baselineKb?: number;
+}
+/** The regex form of `isCheckoutPath`, for JSON Schema. */
+export declare const CHECKOUT_PATH: RegExp;
+export declare const FILE_HASH: RegExp;
+export declare const REGISTRY_NAMESPACE: RegExp;
+/** A relative path with forward slashes whose only `..` segments come first, so it may leave the project. */
+export declare function isCheckoutPath(value: string): boolean;
+export declare const SCOPE: RegExp;
+export declare function validateMfeflowProject(value: unknown): Issue[];
+export declare function isMfeflowProject(value: unknown): value is MfeflowProject;

package/dist/registry.d.ts

@@ -0,0 +1,49 @@
+import { type Issue } from './validate.js';
+/** `registry/envs/<env>/<name>.json`: what one remote serves in one environment. */
+export interface RegistryEntry {
+    version: string;
+    manifestUrl: string;
+    /** The remote's entry script, read from `mf-manifest.json` at publish time. Production shells register this, not the manifest. */
+    remoteEntry?: string;
+    /** How `remoteEntry` loads (`module` for ESM). Needed by shells that register it directly. */
+    type?: string;
+    /** The global `remoteEntry` defines when it differs from the remote's name. */
+    entryGlobalName?: string;
+    /** Per expose (`./App`), the JS and CSS files it needs before it renders. The edge turns these into preload hints. */
+    exposes?: Record<string, string[]>;
+    previous?: string;
+    owner?: string;
+    rollout?: {
+        candidate: string;
+        stable: string;
+        percent: number;
+    };
+}
+/** What the shell fetches at boot. */
+export interface RegistryIndex {
+    shell?: string;
+    env?: string;
+    generatedAt?: string;
+    remotes: RegistryIndexRemote[];
+}
+export interface RegistryIndexRemote {
+    name: string;
+    /** `mf-manifest.json` URL. */
+    entry: string;
+    /** Entry script URL; shells register it in place of `entry` when present. */
+    remoteEntry?: string;
+    /** How `remoteEntry` loads (`module` for ESM). */
+    type?: string;
+    /** The global `remoteEntry` defines when it differs from `name`. */
+    entryGlobalName?: string;
+    /** Per expose, the files to preload. Not inlined into the shell's HTML. */
+    exposes?: Record<string, string[]>;
+    version?: string;
+    routes?: string[];
+    owner?: string;
+}
+export declare const VERSION: RegExp;
+export declare function validateRegistryEntry(value: unknown): Issue[];
+export declare function validateRegistryIndex(value: unknown): Issue[];
+export declare function isRegistryEntry(value: unknown): value is RegistryEntry;
+export declare function isRegistryIndex(value: unknown): value is RegistryIndex;

package/dist/validate.d.ts

@@ -0,0 +1,32 @@
+export interface Issue {
+    /** Where, e.g. `routes[0]` or `rollout.percent`. Empty for the root. */
+    path: string;
+    message: string;
+}
+export type Obj = Record<string, unknown>;
+export declare function isObj(value: unknown): value is Obj;
+export declare class Checker {
+    readonly issues: Issue[];
+    add(path: string, message: string): void;
+    /** Reports a missing or wrong-typed string and returns it when valid. */
+    string(obj: Obj, key: string, path: string, opts?: {
+        required?: boolean;
+        pattern?: RegExp;
+        hint?: string;
+    }): string | undefined;
+    stringArray(obj: Obj, key: string, path: string, opts?: {
+        required?: boolean;
+        pattern?: RegExp;
+        hint?: string;
+    }): string[];
+    number(obj: Obj, key: string, path: string, opts?: {
+        required?: boolean;
+        min?: number;
+        max?: number;
+    }): number | undefined;
+    object(obj: Obj, key: string, path: string, required?: boolean): Obj | undefined;
+}
+export declare function isUrl(value: string): boolean;
+/** The regex form of `isSafeRelativePath`, for JSON Schema. */
+export declare const SAFE_RELATIVE_PATH: RegExp;
+export declare function isSafeRelativePath(value: string): boolean;

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@mfeflow/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Types, validators and JSON Schemas for mfeflow: mfe.json ownership manifests, mfeflow.json project state, and the remote registry (entries and index).",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "json-schema",
+    "manifest",
+    "registry",
+    "validation",
+    "react",
+    "rsbuild"
+  ],
+  "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/contracts"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./entry": {
+      "types": "./dist/entry.d.ts",
+      "import": "./dist/entry.js",
+      "default": "./dist/entry.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@rslib/core": "1.0.5",
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2"
+  },
+  "sideEffects": false,
+  "mfeflow": {
+    "bucket": "stateless"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }