@mfeflow/contracts 0.4.0 → 0.5.0

package/dist/entry.d.ts

@@ -5,6 +5,51 @@ export declare const ENTRY_TYPES: readonly string[];
  * also hold `-`, as the `globalName` in `mf-manifest.json` does for a remote like `my-app`.
  */
 export declare const GLOBAL_NAME: RegExp;
+/** A Module Federation name that is also safe as a plain object key. */
+export declare const isRemoteName: (value: string) => boolean;
+export declare const ROUTE: RegExp;
+export declare const EXPOSE: RegExp;
+/** One remote of the registry index, the shape the shell, the edge, the CLI and the dev registry share. */
+export interface RegistryIndexRemote {
+    /** Module Federation name. */
+    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 (`./App`), the files to preload. Not inlined into the shell's HTML. */
+    exposes?: Record<string, string[]>;
+    version?: string;
+    routes?: string[];
+    owner?: string;
+    /** The version served before `version`; what a rollback returns to. */
+    previous?: string;
+    /** Older versions served, newest first and bounded. */
+    history?: string[];
+    /** Set after a rollback: the version that was served and was moved away from. Never a rollback target. */
+    rolledBackFrom?: string;
+}
+/** What the shell fetches at boot. */
+export interface RegistryIndex {
+    shell?: string;
+    env?: string;
+    generatedAt?: string;
+    remotes: RegistryIndexRemote[];
+}
+export interface RegistryIssue {
+    /** Relative to the value checked, e.g. `type` or `exposes./App[0]`. */
+    path: string;
+    message: string;
+}
+/** Problems with the entry script fields a registry entry and an index remote share. */
+export declare function remoteFileIssues(obj: Record<string, unknown>): RegistryIssue[];
+/** Every problem with one registry index remote; empty when it is valid. Browser-safe: the shell runs it. */
+export declare function registryRemoteIssues(value: unknown): RegistryIssue[];
+export declare function isRegistryIndexRemote(value: unknown): value is RegistryIndexRemote;
 /** The registry remote fields the shell and the edge read; everything else is dropped. */
 export declare const REGISTRY_REMOTE_FIELDS: readonly string[];
 /** A copy of `remote` with only the whitelisted fields that are set. */

package/dist/entry.js

@@ -20,19 +20,156 @@ const ENTRY_TYPES = [
     'system'
 ];
 const GLOBAL_NAME = /^[A-Za-z_$][\w$-]*$/;
+const RESERVED_NAMES = new Set([
+    '__proto__',
+    'constructor',
+    'prototype'
+]);
+const isRemoteName = (value)=>GLOBAL_NAME.test(value) && !RESERVED_NAMES.has(value);
+const ROUTE = /^\/[A-Za-z0-9/_:*.-]*$/;
+const EXPOSE = /^\.\/[A-Za-z0-9_/-]+$/;
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+function isHttpUrl(value) {
+    try {
+        const { protocol } = new URL(value);
+        return 'https:' === protocol || 'http:' === protocol;
+    } catch  {
+        return false;
+    }
+}
+function stringField(obj, key, out, check, required = false) {
+    const value = obj[key];
+    if (void 0 === value) {
+        if (required) out.push({
+            path: key,
+            message: 'is required'
+        });
+    } else if ('string' != typeof value) out.push({
+        path: key,
+        message: 'must be a string'
+    });
+    else if (check && !check.test(value)) out.push({
+        path: key,
+        message: check.hint
+    });
+}
+const URL_CHECK = {
+    test: isHttpUrl,
+    hint: 'must be an http(s) URL'
+};
+function remoteFileIssues(obj) {
+    const out = [];
+    stringField(obj, 'remoteEntry', out, URL_CHECK);
+    stringField(obj, 'type', out, {
+        test: (value)=>ENTRY_TYPES.includes(value),
+        hint: `must be a Module Federation entry type: ${ENTRY_TYPES.join(', ')}`
+    });
+    stringField(obj, 'entryGlobalName', out, {
+        test: (value)=>GLOBAL_NAME.test(value),
+        hint: 'must be a JavaScript global name (letters, digits, _, $, -; not starting with a digit)'
+    });
+    const exposes = obj.exposes;
+    if (void 0 === exposes) return out;
+    if (!isRecord(exposes)) return [
+        ...out,
+        {
+            path: 'exposes',
+            message: 'must be an object'
+        }
+    ];
+    for (const [expose, files] of Object.entries(exposes)){
+        const at = `exposes.${expose}`;
+        if (!EXPOSE.test(expose)) out.push({
+            path: at,
+            message: 'must look like "./App"'
+        });
+        if (!Array.isArray(files)) {
+            out.push({
+                path: at,
+                message: 'must be an array of URLs'
+            });
+            continue;
+        }
+        files.forEach((file, i)=>{
+            if ('string' != typeof file || !isHttpUrl(file)) out.push({
+                path: `${at}[${String(i)}]`,
+                message: 'must be an http(s) URL'
+            });
+        });
+    }
+    return out;
+}
+function registryRemoteIssues(value) {
+    if (!isRecord(value)) return [
+        {
+            path: '',
+            message: 'must be an object'
+        }
+    ];
+    const out = [];
+    stringField(value, 'name', out, {
+        test: isRemoteName,
+        hint: 'must be a Module Federation name'
+    }, true);
+    stringField(value, 'entry', out, URL_CHECK, true);
+    stringField(value, 'version', out);
+    stringField(value, 'owner', out);
+    stringField(value, 'previous', out);
+    stringField(value, 'rolledBackFrom', out);
+    const history = value.history;
+    if (void 0 !== history) if (Array.isArray(history)) history.forEach((version, i)=>{
+        if ('string' != typeof version) out.push({
+            path: `history[${String(i)}]`,
+            message: 'must be a string'
+        });
+    });
+    else out.push({
+        path: 'history',
+        message: 'must be an array of strings'
+    });
+    const routes = value.routes;
+    if (void 0 !== routes) if (Array.isArray(routes)) routes.forEach((route, i)=>{
+        const at = `routes[${String(i)}]`;
+        if ('string' != typeof route) out.push({
+            path: at,
+            message: 'must be a string'
+        });
+        else if (!ROUTE.test(route)) out.push({
+            path: at,
+            message: 'must start with "/"'
+        });
+    });
+    else out.push({
+        path: 'routes',
+        message: 'must be an array of strings'
+    });
+    return [
+        ...out,
+        ...remoteFileIssues(value)
+    ];
+}
+function isRegistryIndexRemote(value) {
+    return 0 === registryRemoteIssues(value).length;
+}
 const REGISTRY_REMOTE_FIELDS = [
     'name',
     'entry',
     'remoteEntry',
     'type',
     'entryGlobalName',
+    'exposes',
     'version',
     'owner',
-    'routes'
+    'routes',
+    'previous',
+    'history',
+    'rolledBackFrom'
 ];
 function pickRegistryFields(remote) {
     const out = {};
     for (const [key, value] of Object.entries(remote))if (void 0 !== value && REGISTRY_REMOTE_FIELDS.includes(key)) out[key] = value;
     return out;
 }
-export { ENTRY_TYPES, GLOBAL_NAME, REGISTRY_REMOTE_FIELDS, pickRegistryFields };
+export { ENTRY_TYPES, EXPOSE, GLOBAL_NAME, REGISTRY_REMOTE_FIELDS, ROUTE, isRegistryIndexRemote, isRemoteName, pickRegistryFields, registryRemoteIssues, remoteFileIssues };

package/dist/feature-registry.d.ts

@@ -29,3 +29,18 @@ export declare function registryTemplateProblem(template: string): string | unde
 export declare function registryIndexUrl(template: string): string;
 export declare function validateFeatureRegistryIndex(value: unknown): Issue[];
 export declare function isFeatureRegistryIndex(value: unknown): value is FeatureRegistryIndex;
+/**
+ * True when `hostname` (as `URL.hostname` spells it) is the machine itself or a private network:
+ * localhost, 127/8, ::1, 10/8, 172.16/12, 192.168/16, 169.254/16, 100.64/10, 192.0.0/24, 0/8, fc00::/7,
+ * fe80::/10, fec0::/10, IPv4-compatible, IPv4-mapped, NAT64 and 6to4 IPv6 forms that hold one of
+ * those, and names ending .localhost, .internal or .local.
+ * Only the literal host is looked at; a public name that resolves to a private address is not caught.
+ */
+export declare function isPrivateHost(hostname: string): boolean;
+/**
+ * `url` with the values of token-like query parameters (token, key, sig, auth, password, secret,
+ * X-Amz-*) and any user name or password replaced by `***`. Works on templates too, so `{name}` stays.
+ */
+export declare function redactUrl(url: string): string;
+/** `text` with every http(s) URL in it passed through `redactUrl`, for messages that quote one. */
+export declare function redactUrlsIn(text: string): string;

package/dist/html-injection.d.ts

@@ -18,7 +18,8 @@ export interface InjectionOptions {
  * index) and preload hints for the files each remote the route renders needs.
  * Everything the runtime reads from the fetched index is inlined, so both
  * paths register the same remotes; only the per-expose `exposes` file lists
- * stay out of the page.
+ * and the rollback fields (`previous`, `history`, `rolledBackFrom`) stay out
+ * of the page.
  *
  * Hints match how the browser will request each file, or it downloads twice:
  * classic scripts and styles are `rel="preload"` without `crossorigin`; the

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-export { isSafeRelativePath, type Issue } from './validate.js';
+export { isPortableRelativePath, isSafeRelativePath, type Issue } from './validate.js';
 export { ANALYTICS_EVENT, EVENT_NAME, EXPOSE, isMfeManifest, MFE_NAME, ROUTE, validateMfeManifest, type MfeManifest, } from './mfe-manifest.js';
+export { routesOverlap } from './routes.js';
 export { assetsFromManifest, type RemoteAssets } from './manifest-assets.js';
+export { remoteDistFiles, type RemoteDistFiles } from './remote-dist.js';
+export { judgeRemoteInitial, primaryExpose, type RemoteInitialVerdict } from './remote-budget.js';
 export { injectIntoHead, registryInjection, type InjectionOptions, type RouteNeed, } from './html-injection.js';
-export { isRegistryEntry, isRegistryIndex, validateRegistryEntry, validateRegistryIndex, type RegistryEntry, type RegistryIndex, type RegistryIndexRemote, } from './registry.js';
-export { isFeatureRegistryIndex, isLoopbackHttp, isRegistryProtocol, registryIndexUrl, registryTemplateProblem, validateFeatureRegistryIndex, MAX_DESCRIPTION, MAX_INDEX_ITEMS, REGISTRY_ITEM_NAME, type FeatureRegistryIndex, type FeatureRegistryItem, } from './feature-registry.js';
-export { FILE_HASH, REGISTRY_NAMESPACE, isMfeflowProject, validateMfeflowProject, type MfeflowProject, type ProjectBudget, } from './project.js';
+export { isRegistryEntry, isRegistryIndex, isRegistryIndexRemote, registryRemoteIssues, ROUTE_OVERLAP, validateRegistryEntry, validateRegistryIndex, type RegistryEntry, type RegistryIndex, type RegistryIndexRemote, } from './registry.js';
+export { isFeatureRegistryIndex, isLoopbackHttp, isPrivateHost, isRegistryProtocol, redactUrl, redactUrlsIn, registryIndexUrl, registryTemplateProblem, validateFeatureRegistryIndex, MAX_DESCRIPTION, MAX_INDEX_ITEMS, REGISTRY_ITEM_NAME, type FeatureRegistryIndex, type FeatureRegistryItem, } from './feature-registry.js';
+export { FILE_HASH, PROJECT_REPOS, REGISTRY_HOST, REGISTRY_NAMESPACE, isMfeflowProject, validateMfeflowProject, type MfeflowProject, type ProjectBudget, type ProjectRegistry, } from './project.js';
 export { COST_MODEL, judgeCost, round1, splitScripts, type CostLine, type CostModel, type CostSample, type CostVerdict, } from './cost-model.js';
 export { FEATURE_CONDITION, FEATURE_NAME, isFeatureManifest, TRANSFORM_OPS, validateFeatureManifest, type AddBootStepOp, type AddEnvKeyOp, type AddImportOp, type AddRouteOp, type AddSharedOp, type AddWorkflowStepOp, type EnvValidator, type FeatureCondition, type FeatureDependency, type FeatureFile, type FeatureManifest, type FeatureMigration, type FeaturePrompt, type FeatureScript, type FeatureTarget, type Literal, type PromptValue, type TransformOp, type TransformOpName, type WorkflowStep, type WrapProviderOp, } from './feature.js';
 export { DOCS_URL, SCHEMA_URLS, errorDocsUrl, type SchemaName } from './docs.js';

package/dist/index.js

@@ -1,13 +1,17 @@
-import { ENTRY_TYPES, GLOBAL_NAME, pickRegistryFields } from "./entry.js";
+import { registryRemoteIssues, GLOBAL_NAME, remoteFileIssues, ENTRY_TYPES, pickRegistryFields, EXPOSE, isRemoteName, ROUTE } from "./entry.js";
 function isObj(value) {
     return 'object' == typeof value && null !== value && !Array.isArray(value);
 }
 class Checker {
     issues = [];
-    add(path, message) {
-        this.issues.push({
+    add(path, message, code) {
+        this.issues.push(void 0 === code ? {
             path,
             message
+        } : {
+            path,
+            message,
+            code
         });
     }
     string(obj, key, path, opts = {}) {
@@ -78,9 +82,12 @@ function isSafeRelativePath(value) {
     if (value.startsWith('/') || /^[A-Za-z]:/.test(value)) return false;
     return value.split('/').every((part)=>'' !== part && '.' !== part && '..' !== part);
 }
+const DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+function isPortableRelativePath(value) {
+    if (!isSafeRelativePath(value)) return false;
+    return value.split('/').every((part)=>!part.includes(':') && !DEVICE_NAME.test(part) && !/[. ]$/.test(part));
+}
 const MFE_NAME = /^[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*)*$/;
-const ROUTE = /^\/[A-Za-z0-9/_:*.-]*$/;
-const EXPOSE = /^\.\/[A-Za-z0-9_/-]+$/;
 const EVENT_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+\.v[1-9][0-9]*$/;
 const ANALYTICS_EVENT = /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/;
 function validateMfeManifest(value) {
@@ -146,6 +153,32 @@ function validateMfeManifest(value) {
 function isMfeManifest(value) {
     return 0 === validateMfeManifest(value).length;
 }
+function segments(route) {
+    return route.toLowerCase().split('/').filter(Boolean);
+}
+const isParam = (segment)=>segment.startsWith(':');
+const isWild = (segment)=>segment.endsWith('*');
+const prefixOf = (segment)=>isParam(segment) ? '' : segment.slice(0, -1);
+const tailAt = (list, i)=>i === list.length - 1 && isWild(list[i] ?? '');
+function segmentsMeet(x, y) {
+    if (isWild(x) && isWild(y)) return x.startsWith(prefixOf(y)) || y.startsWith(prefixOf(x));
+    if (isWild(x)) return isParam(y) || y.startsWith(prefixOf(x));
+    if (isWild(y)) return isParam(x) || x.startsWith(prefixOf(y));
+    return x === y || isParam(x) || isParam(y);
+}
+function routesOverlap(a, b) {
+    const left = segments(a);
+    const right = segments(b);
+    for(let i = 0; i < Math.max(left.length, right.length); i += 1){
+        const x = left[i];
+        const y = right[i];
+        if (void 0 === x) return tailAt(right, i) && '' === prefixOf(y ?? '');
+        if (void 0 === y) return tailAt(left, i) && '' === prefixOf(x);
+        if (!segmentsMeet(x, y)) return false;
+        if (tailAt(left, i) || tailAt(right, i)) break;
+    }
+    return true;
+}
 function fail(why) {
     throw new Error(`mf-manifest.json: ${why}`);
 }
@@ -226,6 +259,107 @@ function assetsFromManifest(manifest, manifestUrl, options = {}) {
         }
     };
 }
+const DIST_ORIGIN = 'https://dist.invalid';
+const SCRIPT = /\.[cm]?js$/;
+function distPath(url) {
+    try {
+        return decodeURIComponent(new URL(url).pathname).replace(/^\//, '');
+    } catch  {
+        return;
+    }
+}
+function remoteDistFiles(manifest) {
+    if (!isObj(manifest) || !isObj(manifest.metaData) || !isObj(manifest.metaData.remoteEntry)) return;
+    const local = {
+        ...manifest,
+        metaData: {
+            ...manifest.metaData,
+            publicPath: 'auto',
+            getPublicPath: void 0,
+            globalName: void 0,
+            remoteEntry: {
+                ...manifest.metaData.remoteEntry,
+                type: void 0
+            }
+        }
+    };
+    let assets;
+    try {
+        assets = assetsFromManifest(local, `${DIST_ORIGIN}/mf-manifest.json`);
+    } catch  {
+        return;
+    }
+    const entry = void 0 === assets.remoteEntry ? void 0 : distPath(assets.remoteEntry);
+    if (void 0 === entry) return;
+    const exposes = {};
+    for (const [name, urls] of Object.entries(assets.exposes))exposes[name] = urls.flatMap((url)=>distPath(url) ?? []).filter((f)=>SCRIPT.test(f));
+    return {
+        entry,
+        exposes
+    };
+}
+const COST_MODEL = {
+    lcpDeltaMs: 300,
+    shellKb: 32,
+    remoteKb: 10
+};
+const KB = 1024;
+const round1 = (value)=>Math.round(10 * value) / 10;
+const line = (actual, budget)=>({
+        budget,
+        actual,
+        pass: actual <= budget
+    });
+function judgeCost(sample, model = COST_MODEL) {
+    const lcp = line(Math.round(sample.lcpDeltaMs), model.lcpDeltaMs);
+    const shell = line(round1((sample.shellBytes - sample.monolithBytes) / KB), model.shellKb);
+    const remotes = Object.entries(sample.remoteBytes).toSorted(([a], [b])=>a < b ? -1 : a > b ? 1 : 0).map(([name, bytes])=>Object.assign(line(round1(bytes / KB), model.remoteKb), {
+            name
+        }));
+    return {
+        pass: lcp.pass && shell.pass && remotes.every((r)=>r.pass),
+        lcp,
+        shell,
+        remotes
+    };
+}
+const REMOTE_PATH = /^\/mfe\/([^/]+)\//;
+function splitScripts(requests) {
+    let shellBytes = 0;
+    const remoteBytes = {};
+    for (const request of requests){
+        if ('Script' !== request.type) continue;
+        const remote = REMOTE_PATH.exec(request.path)?.[1];
+        if (void 0 === remote) shellBytes += request.bytes;
+        else remoteBytes[remote] = (remoteBytes[remote] ?? 0) + request.bytes;
+    }
+    return {
+        shellBytes,
+        remoteBytes
+    };
+}
+const remote_budget_KB = 1024;
+function primaryExpose(names) {
+    return names.includes('./App') ? './App' : names[0];
+}
+function judgeRemoteInitial(bytes, budgetKb, model = COST_MODEL) {
+    const totalKb = round1((bytes.entryBytes + bytes.exposeBytes) / remote_budget_KB);
+    if (void 0 !== budgetKb) return {
+        kb: totalKb,
+        totalKb,
+        limitKb: budgetKb,
+        pass: totalKb <= budgetKb,
+        source: 'mfe.json'
+    };
+    const kb = round1(bytes.entryBytes / remote_budget_KB);
+    return {
+        kb,
+        totalKb,
+        limitKb: model.remoteKb,
+        pass: kb <= model.remoteKb,
+        source: 'cost-model'
+    };
+}
 const SCRIPT_UNSAFE = new RegExp('[<\\u2028\\u2029]', 'g');
 function jsonForScript(value) {
     return JSON.stringify(value).replace(SCRIPT_UNSAFE, (c)=>`\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
@@ -237,9 +371,15 @@ const ESM_TYPES = new Set([
     'module',
     'esm'
 ]);
+const NOT_INLINED = new Set([
+    'exposes',
+    'previous',
+    'history',
+    'rolledBackFrom'
+]);
 function registryInjection(index, needs, options = {}) {
     const inline = {
-        remotes: index.remotes.map((remote)=>pickRegistryFields(remote))
+        remotes: index.remotes.map((remote)=>Object.fromEntries(Object.entries(pickRegistryFields(remote)).filter(([key])=>!NOT_INLINED.has(key))))
     };
     let html = `<script>window.__MFE_REGISTRY__=${jsonForScript(inline)}</script>`;
     const seen = new Set();
@@ -307,36 +447,13 @@ function injectIntoHead(html, snippet) {
     const end = -1 === charset ? open : charset;
     return html.slice(0, end) + snippet + html.slice(end);
 }
-const ENTRY_TYPE = new RegExp(`^(?:${ENTRY_TYPES.join('|')})$`);
+const ROUTE_OVERLAP = 'route-overlap';
 const VERSION = /^[0-9A-Za-z.+-]+$/;
-function checkRemoteFiles(c, obj, at) {
-    const entry = c.string(obj, 'remoteEntry', at, {
-        required: false
-    });
-    if (void 0 !== entry && !isUrl(entry)) c.add(at ? `${at}.remoteEntry` : 'remoteEntry', 'must be an http(s) URL');
-    c.string(obj, 'type', at, {
-        required: false,
-        pattern: ENTRY_TYPE,
-        hint: `must be a Module Federation entry type: ${ENTRY_TYPES.join(', ')}`
-    });
-    c.string(obj, 'entryGlobalName', at, {
-        required: false,
-        pattern: GLOBAL_NAME,
-        hint: 'must be a JavaScript global name (letters, digits, _, $, -; not starting with a digit)'
-    });
-    const exposes = c.object(obj, 'exposes', at, false);
-    if (!exposes) return;
-    const base = at ? `${at}.exposes` : 'exposes';
-    for (const [expose, files] of Object.entries(exposes)){
-        if (!EXPOSE.test(expose)) c.add(`${base}.${expose}`, 'must look like "./App"');
-        if (!Array.isArray(files)) {
-            c.add(`${base}.${expose}`, 'must be an array of URLs');
-            continue;
-        }
-        files.forEach((file, i)=>{
-            if ('string' != typeof file || !isUrl(file)) c.add(`${base}.${expose}[${String(i)}]`, 'must be an http(s) URL');
-        });
-    }
+function addIssues(c, issues, at) {
+    for (const issue of issues)c.add([
+        at,
+        issue.path
+    ].filter(Boolean).join('.'), issue.message);
 }
 function validateRegistryEntry(value) {
     const c = new Checker();
@@ -350,7 +467,7 @@ function validateRegistryEntry(value) {
     });
     const url = c.string(value, 'manifestUrl', '');
     if (void 0 !== url && !isUrl(url)) c.add('manifestUrl', 'must be an http(s) URL');
-    checkRemoteFiles(c, value, '');
+    addIssues(c, remoteFileIssues(value), '');
     c.string(value, 'previous', '', {
         required: false,
         pattern: VERSION,
@@ -395,37 +512,21 @@ function validateRegistryIndex(value) {
         return c.issues;
     }
     const names = new Set();
-    const claimed = new Map();
+    const claimed = [];
     remotes.forEach((remote, i)=>{
         const at = `remotes[${String(i)}]`;
         if (!isObj(remote)) return void c.add(at, 'must be an object');
-        const name = c.string(remote, 'name', at, {
-            pattern: MFE_NAME,
-            hint: 'must be a Module Federation name'
-        });
-        const entry = c.string(remote, 'entry', at);
-        if (void 0 !== entry && !isUrl(entry)) c.add(`${at}.entry`, 'must be an http(s) URL');
-        checkRemoteFiles(c, remote, at);
-        c.string(remote, 'version', at, {
-            required: false
-        });
-        c.string(remote, 'owner', at, {
-            required: false
-        });
-        const routes = c.stringArray(remote, 'routes', at, {
-            required: false,
-            pattern: ROUTE,
-            hint: 'must start with "/"'
+        addIssues(c, registryRemoteIssues(remote), at);
+        const { name } = remote;
+        if ('string' != typeof name || !isRemoteName(name)) return;
+        if (names.has(name)) c.add(`${at}.name`, `duplicate remote "${name}"`);
+        names.add(name);
+        const routes = Array.isArray(remote.routes) ? remote.routes.filter((r)=>'string' == typeof r && ROUTE.test(r)) : [];
+        for (const route of routes)for (const other of claimed)if (other.remote !== name && routesOverlap(route, other.route)) c.add(`${at}.routes`, `route "${route}" of "${name}" overlaps route "${other.route}" of "${other.remote}"`, ROUTE_OVERLAP);
+        for (const route of routes)claimed.push({
+            remote: name,
+            route
         });
-        if (void 0 !== name) {
-            if (names.has(name)) c.add(`${at}.name`, `duplicate remote "${name}"`);
-            names.add(name);
-            for (const route of routes){
-                const owner = claimed.get(route);
-                if (void 0 !== owner && owner !== name) c.add(`${at}.routes`, `route "${route}" is already claimed by "${owner}"`);
-                claimed.set(route, name);
-            }
-        }
     });
     return c.issues;
 }
@@ -528,6 +629,90 @@ function validateFeatureRegistryIndex(value) {
 function isFeatureRegistryIndex(value) {
     return 0 === validateFeatureRegistryIndex(value).length;
 }
+function ipv4Octets(host) {
+    const parts = host.split('.');
+    if (4 !== parts.length) return;
+    const octets = parts.map((part)=>/^\d{1,3}$/.test(part) ? Number(part) : 0 / 0);
+    return octets.every((n)=>n <= 255) ? octets : void 0;
+}
+function isPrivateIpv4([a = 0, b = 0, c = 0]) {
+    return 0 === a || 10 === a || 127 === a || 100 === a && b >= 64 && b <= 127 || 169 === a && 254 === b || 172 === a && b >= 16 && b <= 31 || 192 === a && 168 === b || 192 === a && 0 === b && 0 === c;
+}
+const side = (part)=>'' === part ? [] : part.split(':');
+function ipv6Groups(host) {
+    const [head = '', tail, ...rest] = host.split('::');
+    if (rest.length > 0) return;
+    const headGroups = side(head);
+    const groups = [
+        ...headGroups,
+        ...void 0 === tail ? [] : side(tail)
+    ];
+    if (groups.some((g)=>!/^[0-9a-f]{1,4}$/.test(g))) return;
+    const numbers = groups.map((g)=>Number.parseInt(g, 16));
+    if (void 0 === tail) return 8 === numbers.length ? numbers : void 0;
+    const missing = 8 - numbers.length;
+    if (missing < 1) return;
+    return [
+        ...numbers.slice(0, headGroups.length),
+        ...Array.from({
+            length: missing
+        }, ()=>0),
+        ...numbers.slice(headGroups.length)
+    ];
+}
+const embedded = (hi = 0, lo = 0)=>[
+        hi >> 8,
+        0xff & hi,
+        lo >> 8,
+        0xff & lo
+    ];
+function isPrivateIpv6(host) {
+    const groups = ipv6Groups(host);
+    if (void 0 === groups) return false;
+    const [g0 = 0, g1 = 0] = groups;
+    const zeros = (from, to)=>groups.slice(from, to).every((g)=>0 === g);
+    if (zeros(0, 6)) return isPrivateIpv4(embedded(groups[6], groups[7]));
+    if ((0xfe00 & g0) === 0xfc00 || (0xffc0 & g0) === 0xfe80 || (0xffc0 & g0) === 0xfec0) return true;
+    const mapped = zeros(0, 5) && 0xffff === groups[5];
+    const nat64 = 0x64 === g0 && 0xff9b === g1 && zeros(2, 6);
+    if (mapped || nat64) return isPrivateIpv4(embedded(groups[6], groups[7]));
+    return 0x2002 === g0 && isPrivateIpv4(embedded(groups[1], groups[2]));
+}
+function isPrivateHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    if ('localhost' === host || /\.(?:localhost|internal|local)$/.test(host)) return true;
+    if (host.includes(':')) return isPrivateIpv6(host);
+    const octets = ipv4Octets(host);
+    return void 0 !== octets && isPrivateIpv4(octets);
+}
+const SECRET_PARAM = /token|key|sig|auth|passw|secret|credential|x-amz-|(?:^|[_-])(?:jwt|bearer|session|pat|access|code)(?:$|[_-])/i;
+const URL_PARTS = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#@]*@)?([^?#]*)(\?[^#]*)?(#.*)?$/i;
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    } catch  {
+        return value;
+    }
+}
+function redactUrl(url) {
+    const parts = URL_PARTS.exec(url);
+    if (null === parts) return url;
+    const [, scheme = '', userinfo, rest = '', query, hash] = parts;
+    const search = void 0 === query ? '' : `?${hideSecrets(query.slice(1))}`;
+    const fragment = void 0 === hash ? '' : `#${hideSecrets(hash.slice(1))}`;
+    return `${scheme}${void 0 === userinfo ? '' : '***@'}${rest}${search}${fragment}`;
+}
+function hideSecrets(params) {
+    return params.split(/([&;])/).map((part)=>{
+        const eq = part.indexOf('=');
+        if (eq <= 0) return part;
+        const key = part.slice(0, eq);
+        return SECRET_PARAM.test(safeDecode(key)) ? `${key}=***` : part;
+    }).join('');
+}
+function redactUrlsIn(text) {
+    return text.replaceAll(/https?:\/\/[^\s"'<>]+/gi, (found)=>redactUrl(found));
+}
 const project_SEGMENT = String.raw`(?!\.\.?(?:/|$))[^/\\\u0000]+`;
 const CHECKOUT_PATH = new RegExp(`^(?:(?![A-Za-z]:)(?:\\.\\.(?:/\\.\\.)*(?:/${project_SEGMENT})*|${project_SEGMENT}(?:/${project_SEGMENT})*)|(?:/|[A-Za-z]:/)${project_SEGMENT}(?:/${project_SEGMENT})*)$`);
 const FILE_HASH = /^sha256-[0-9a-f]{64}$/;
@@ -545,7 +730,14 @@ function isCheckoutPath(value) {
     const rest = -1 === climbing ? [] : parts.slice(climbing);
     return rest.every((part)=>'' !== part && '.' !== part && '..' !== part);
 }
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const REGISTRY_HOST = /^(?:file:\S.*|s3:\/\/[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](?:\/\S*)?)$/;
 const SCOPE = /^@[a-z0-9][a-z0-9-._]*$/;
+const PROJECT_REPOS = [
+    'platform',
+    'shell',
+    'remote'
+];
 const FEATURE = /^(@[a-z0-9-]+\/)?[a-z][a-z0-9-]*$/;
 function validateMfeflowProject(value) {
     const c = new Checker();
@@ -554,6 +746,18 @@ function validateMfeflowProject(value) {
         return c.issues;
     }
     if (1 !== value.version) c.add('version', 'must be 1');
+    if ('cli' in value) c.string(value, 'cli', '', {
+        required: false,
+        pattern: SEMVER,
+        hint: 'must be a version like "0.5.0"'
+    });
+    let repo;
+    if ('repo' in value) {
+        repo = c.string(value, 'repo', '', {
+            required: false
+        });
+        if (void 0 !== repo && !PROJECT_REPOS.some((name)=>name === repo)) c.add('repo', 'must be platform, shell or remote');
+    }
     const topology = c.string(value, 'topology', '');
     if (void 0 !== topology && ![
         'monorepo',
@@ -590,7 +794,7 @@ function validateMfeflowProject(value) {
             });
             if (void 0 !== port && !Number.isInteger(port)) c.add(`${at}.port`, 'must be a whole number');
         }
-        if (0 === shells) c.add('apps', 'needs at least one shell');
+        if (0 === shells && 'remote' !== repo) c.add('apps', 'needs at least one shell');
     }
     const features = c.object(value, 'features', '');
     if (features) for (const [name, feature] of Object.entries(features)){
@@ -599,6 +803,10 @@ function validateMfeflowProject(value) {
         if (isObj(feature)) {
             c.string(feature, 'version', at);
             c.object(feature, 'options', at, false);
+            if ('integrity' in feature) {
+                const integrity = c.string(feature, 'integrity', at);
+                if (void 0 !== integrity && !FILE_HASH.test(integrity)) c.add(`${at}.integrity`, 'must be a hash like "sha256-<64 hex characters>"');
+            }
         } else c.add(at, 'must be an object');
     }
     const files = c.object(value, 'files', '', false);
@@ -632,51 +840,27 @@ function validateMfeflowProject(value) {
         required: false,
         min: 1
     });
+    const registry = c.object(value, 'registry', '', false);
+    if (registry) {
+        c.string(registry, 'host', 'registry', {
+            required: false,
+            pattern: REGISTRY_HOST,
+            hint: 'must be file:<dir> or s3://<bucket>[/prefix], with no credentials'
+        });
+        const baseUrl = c.string(registry, 'baseUrl', 'registry', {
+            required: false
+        });
+        if (void 0 !== baseUrl && !(isUrl(baseUrl) && validBaseUrl(baseUrl))) c.add('registry.baseUrl', 'must be an https URL (http only on localhost) without credentials, a query, a fragment or a trailing slash');
+    }
     return c.issues;
 }
+function validBaseUrl(value) {
+    const url = new URL(value);
+    return isRegistryProtocol(url) && '' === url.username && '' === url.password && !/[?#]/.test(value) && !value.endsWith('/');
+}
 function isMfeflowProject(value) {
     return 0 === validateMfeflowProject(value).length;
 }
-const COST_MODEL = {
-    lcpDeltaMs: 300,
-    shellKb: 32,
-    remoteKb: 10
-};
-const KB = 1024;
-const round1 = (value)=>Math.round(10 * value) / 10;
-const line = (actual, budget)=>({
-        budget,
-        actual,
-        pass: actual <= budget
-    });
-function judgeCost(sample, model = COST_MODEL) {
-    const lcp = line(Math.round(sample.lcpDeltaMs), model.lcpDeltaMs);
-    const shell = line(round1((sample.shellBytes - sample.monolithBytes) / KB), model.shellKb);
-    const remotes = Object.entries(sample.remoteBytes).toSorted(([a], [b])=>a < b ? -1 : a > b ? 1 : 0).map(([name, bytes])=>Object.assign(line(round1(bytes / KB), model.remoteKb), {
-            name
-        }));
-    return {
-        pass: lcp.pass && shell.pass && remotes.every((r)=>r.pass),
-        lcp,
-        shell,
-        remotes
-    };
-}
-const REMOTE_PATH = /^\/mfe\/([^/]+)\//;
-function splitScripts(requests) {
-    let shellBytes = 0;
-    const remoteBytes = {};
-    for (const request of requests){
-        if ('Script' !== request.type) continue;
-        const remote = REMOTE_PATH.exec(request.path)?.[1];
-        if (void 0 === remote) shellBytes += request.bytes;
-        else remoteBytes[remote] = (remoteBytes[remote] ?? 0) + request.bytes;
-    }
-    return {
-        shellBytes,
-        remoteBytes
-    };
-}
 const TRANSFORM_OPS = [
     'add-import',
     'wrap-provider',
@@ -1266,6 +1450,12 @@ const JSON_SCHEMAS = {
             version: {
                 const: 1
             },
+            cli: str(SEMVER),
+            repo: {
+                enum: [
+                    ...PROJECT_REPOS
+                ]
+            },
             topology: {
                 enum: [
                     'monorepo',
@@ -1309,7 +1499,8 @@ const JSON_SCHEMAS = {
                     version: str(),
                     options: {
                         type: 'object'
-                    }
+                    },
+                    integrity: str(FILE_HASH)
                 }, [
                     'version'
                 ])
@@ -1348,6 +1539,16 @@ const JSON_SCHEMAS = {
                             minimum: 1
                         }
                     ]))
+            },
+            registry: {
+                type: 'object',
+                properties: {
+                    host: str(REGISTRY_HOST),
+                    baseUrl: {
+                        type: 'string',
+                        pattern: String.raw`^(?:https://[^@\s?#]*[^/@\s?#]|http://(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:/[^@\s?#]*[^/@\s?#])?)$`
+                    }
+                }
             }
         },
         required: [
@@ -1511,7 +1712,10 @@ const JSON_SCHEMAS = {
                     ...remoteFiles,
                     version: str(),
                     routes: json_schema_strings(ROUTE),
-                    owner: str()
+                    owner: str(),
+                    previous: str(),
+                    history: json_schema_strings(),
+                    rolledBackFrom: str()
                 }, [
                     'name',
                     'entry'
@@ -1554,4 +1758,5 @@ const JSON_SCHEMAS = {
         ]
     })
 };
-export { ANALYTICS_EVENT, COST_MODEL, DOCS_URL, EVENT_NAME, EXPOSE, FEATURE_CONDITION, FEATURE_NAME, FILE_HASH, JSON_SCHEMAS, MAX_DESCRIPTION, MAX_INDEX_ITEMS, MFE_NAME, REGISTRY_ITEM_NAME, REGISTRY_NAMESPACE, ROUTE, SCHEMA_URLS, TRANSFORM_OPS, assetsFromManifest, errorDocsUrl, injectIntoHead, isFeatureManifest, isFeatureRegistryIndex, isLoopbackHttp, isMfeManifest, isMfeflowProject, isRegistryEntry, isRegistryIndex, isRegistryProtocol, isSafeRelativePath, judgeCost, registryIndexUrl, registryInjection, registryTemplateProblem, round1, splitScripts, validateFeatureManifest, validateFeatureRegistryIndex, validateMfeManifest, validateMfeflowProject, validateRegistryEntry, validateRegistryIndex };
+export { EXPOSE, ROUTE, isRegistryIndexRemote, registryRemoteIssues } from "./entry.js";
+export { ANALYTICS_EVENT, COST_MODEL, DOCS_URL, EVENT_NAME, FEATURE_CONDITION, FEATURE_NAME, FILE_HASH, JSON_SCHEMAS, MAX_DESCRIPTION, MAX_INDEX_ITEMS, MFE_NAME, PROJECT_REPOS, REGISTRY_HOST, REGISTRY_ITEM_NAME, REGISTRY_NAMESPACE, ROUTE_OVERLAP, SCHEMA_URLS, TRANSFORM_OPS, assetsFromManifest, errorDocsUrl, injectIntoHead, isFeatureManifest, isFeatureRegistryIndex, isLoopbackHttp, isMfeManifest, isMfeflowProject, isPortableRelativePath, isPrivateHost, isRegistryEntry, isRegistryIndex, isRegistryProtocol, isSafeRelativePath, judgeCost, judgeRemoteInitial, primaryExpose, redactUrl, redactUrlsIn, registryIndexUrl, registryInjection, registryTemplateProblem, remoteDistFiles, round1, routesOverlap, splitScripts, validateFeatureManifest, validateFeatureRegistryIndex, validateMfeManifest, validateMfeflowProject, validateRegistryEntry, validateRegistryIndex };

package/dist/mfe-manifest.d.ts

@@ -1,4 +1,6 @@
+import { EXPOSE, ROUTE } from './entry.js';
 import { type Issue } from './validate.js';
+export { EXPOSE, ROUTE };
 /** `mfe.json`: who owns a micro-frontend and what it promises. */
 export interface MfeManifest {
     $schema?: string;
@@ -32,8 +34,6 @@ export interface MfeManifest {
  * 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>.v<major>`, e.g. `cart.item-added.v1`. The same pattern `@mfeflow/event-bus` checks names against. */
 export declare const EVENT_NAME: RegExp;
 /** `<domain>_<object>_<action>`, e.g. `checkout_order_completed`. */

package/dist/project.d.ts

@@ -3,6 +3,10 @@ import { type Issue } from './validate.js';
 export interface MfeflowProject {
     $schema?: string;
     version: 1;
+    /** Version of the CLI that last wrote this file. */
+    cli?: string;
+    /** Which repo this is in a multi-repo setup. Absent means a platform monorepo. */
+    repo?: 'platform' | 'shell' | 'remote';
     topology: 'monorepo' | 'polyrepo' | 'hybrid';
     packageManager: 'pnpm' | 'npm';
     /** npm scope for the project's own packages, e.g. `@shopco`. */
@@ -15,6 +19,8 @@ export interface MfeflowProject {
     features: Record<string, {
         version: string;
         options?: Record<string, unknown>;
+        /** `sha256-<hex>` of the `feature.json` a registry served when the feature was added. Third-party features only. */
+        integrity?: string;
     }>;
     /** Hashes of copied files, so `upgrade` can tell when a file was edited. */
     files?: Record<string, string>;
@@ -24,6 +30,14 @@ export interface MfeflowProject {
     local?: string;
     /** Overrides of the cost-model budget `mfeflow budget` and the perf job check. */
     budget?: ProjectBudget;
+    /** Where `mfeflow deploy`, `promote`, `rollback` and `status` publish by default. */
+    registry?: ProjectRegistry;
+}
+export interface ProjectRegistry {
+    /** `file:<dir>` for a folder, or `s3://<bucket>[/prefix]`. Credentials never go here; they come from the environment. */
+    host?: string;
+    /** Where the host's files are served from (`https://cdn.example.com`), without a trailing slash. */
+    baseUrl?: string;
 }
 export interface ProjectBudget {
     /** JS the shell may add over a one-app build, in KB. Default 32. */
@@ -41,6 +55,10 @@ 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 SEMVER: RegExp;
+/** `file:<dir>` or `s3://<bucket>[/prefix]`. No credentials: `@` and `:` cannot appear in a bucket name. */
+export declare const REGISTRY_HOST: RegExp;
 export declare const SCOPE: RegExp;
+export declare const PROJECT_REPOS: readonly ['platform', 'shell', 'remote'];
 export declare function validateMfeflowProject(value: unknown): Issue[];
 export declare function isMfeflowProject(value: unknown): value is MfeflowProject;

package/dist/registry.d.ts

@@ -1,4 +1,6 @@
+import { isRegistryIndexRemote, registryRemoteIssues, type RegistryIndex, type RegistryIndexRemote } from './entry.js';
 import { type Issue } from './validate.js';
+export { isRegistryIndexRemote, registryRemoteIssues, type RegistryIndex, type RegistryIndexRemote, };
 /** `registry/envs/<env>/<name>.json`: what one remote serves in one environment. */
 export interface RegistryEntry {
     version: string;
@@ -19,29 +21,8 @@ export interface RegistryEntry {
         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;
-}
+/** The `code` of the issues `validateRegistryIndex` reports for overlapping routes. */
+export declare const ROUTE_OVERLAP = "route-overlap";
 export declare const VERSION: RegExp;
 export declare function validateRegistryEntry(value: unknown): Issue[];
 export declare function validateRegistryIndex(value: unknown): Issue[];

package/dist/remote-budget.d.ts

@@ -0,0 +1,21 @@
+import { type CostModel } from './cost-model.js';
+/** The expose a remote's route loads first: `./App`, else the first one. */
+export declare function primaryExpose(names: readonly string[]): string | undefined;
+export interface RemoteInitialVerdict {
+    /** Gzip KB that were judged, one decimal: the entry plus the primary expose, or the entry alone without an `mfe.json` budget. */
+    kb: number;
+    /** Gzip KB of the entry plus the primary expose, whichever was judged. */
+    totalKb: number;
+    limitKb: number;
+    pass: boolean;
+    /** Where the limit came from: the remote's `mfe.json` budget or the cost model. */
+    source: 'mfe.json' | 'cost-model';
+}
+/**
+ * Judges the JS a remote loads first. With an `mfe.json` `budgets.initialJsKb` the entry plus the
+ * primary expose must fit it; without one the entry alone must fit the cost model's `remoteKb`.
+ */
+export declare function judgeRemoteInitial(bytes: {
+    entryBytes: number;
+    exposeBytes: number;
+}, budgetKb: number | undefined, model?: CostModel): RemoteInitialVerdict;

package/dist/remote-dist.d.ts

@@ -0,0 +1,12 @@
+export interface RemoteDistFiles {
+    /** The entry script, as a path inside the build folder. */
+    entry: string;
+    /** expose (`./App`) → the JS files it loads before it renders, as paths inside the build folder. */
+    exposes: Record<string, string[]>;
+}
+/**
+ * The files a remote's build folder holds for its entry and each expose's synchronous JS, read from
+ * its `mf-manifest.json`. Paths resolve against the folder whatever `publicPath` says about where the
+ * files are served. Undefined when the manifest has no usable entry.
+ */
+export declare function remoteDistFiles(manifest: unknown): RemoteDistFiles | undefined;

package/dist/routes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when some URL path matches both routes. Routes compare case-insensitively and ignore a
+ * trailing slash. A `*` on the last segment (`/checkout/*`, `/checkout*`, `/:rest*`) matches any
+ * tail, including none; anywhere else it stays inside one segment. `:param` matches one segment.
+ */
+export declare function routesOverlap(a: string, b: string): boolean;

package/dist/validate.d.ts

@@ -2,12 +2,14 @@ export interface Issue {
     /** Where, e.g. `routes[0]` or `rollout.percent`. Empty for the root. */
     path: string;
     message: string;
+    /** Set on issues a caller may want to tell apart, e.g. `route-overlap`. */
+    code?: 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;
+    add(path: string, message: string, code?: string): void;
     /** Reports a missing or wrong-typed string and returns it when valid. */
     string(obj: Obj, key: string, path: string, opts?: {
         required?: boolean;
@@ -30,3 +32,8 @@ 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;
+/**
+ * `isSafeRelativePath` plus what a file on any OS can be named: no `:` (drive letters, NTFS
+ * streams), no Windows device names (`CON`, `nul.txt`, `COM1`) and no segment ending in a dot or space.
+ */
+export declare function isPortableRelativePath(value: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfeflow/contracts",
-  "version": "0.4.0",
+  "version": "0.5.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",