@mfeflow/contracts 0.5.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 Part of [mfeflow](https://github.com/mfeflow/mfeflow), the React micro-frontend boilerplate and platform kit.
 
-Types, validators and JSON Schemas for `mfe.json`, `mfeflow.json` and the remote registry. Pre-1.0: minor versions may change the API.
+Types, validators and JSON Schemas for `mfeflow.app.json`, `mfeflow.json` and the remote registry. Pre-1.0: minor versions may change the API.
 
 ```sh
 pnpm add @mfeflow/contracts

package/dist/docs.d.ts

@@ -2,7 +2,8 @@
 export declare const DOCS_URL = "https://mfeflow.github.io/mfeflow";
 /** Where the JSON Schemas are published, for `$schema` in editors. */
 export declare const SCHEMA_URLS: {
-    readonly mfe: "https://mfeflow.github.io/mfeflow/schema/mfe.json";
+    /** `mfeflow.app.json`, the file in each app's folder. */
+    readonly mfe: "https://mfeflow.github.io/mfeflow/schema/mfeflow-app.json";
     readonly project: "https://mfeflow.github.io/mfeflow/schema/mfeflow.json";
     readonly feature: "https://mfeflow.github.io/mfeflow/schema/feature.json";
     readonly registryEntry: "https://mfeflow.github.io/mfeflow/schema/registry-entry.json";
@@ -10,5 +11,10 @@ export declare const SCHEMA_URLS: {
     readonly featureRegistryIndex: "https://mfeflow.github.io/mfeflow/schema/feature-registry-index.json";
 };
 export type SchemaName = keyof typeof SCHEMA_URLS;
+/**
+ * Old schema URLs that still serve a schema, so `$schema` lines written before a rename keep
+ * resolving. Each maps to the schema now published at its `SCHEMA_URLS` address.
+ */
+export declare const SCHEMA_ALIASES: Readonly<Record<string, SchemaName>>;
 /** The docs page for an error code such as `E102`. */
 export declare function errorDocsUrl(code: string): string;

package/dist/index.d.ts

@@ -7,8 +7,8 @@ export { judgeRemoteInitial, primaryExpose, type RemoteInitialVerdict } from './
 export { injectIntoHead, registryInjection, type InjectionOptions, type RouteNeed, } from './html-injection.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 { ENV_KEY_NAME, 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';
+export { DOCS_URL, SCHEMA_ALIASES, SCHEMA_URLS, errorDocsUrl, type SchemaName } from './docs.js';
 export { JSON_SCHEMAS } from './json-schema.js';

package/dist/index.js

@@ -349,7 +349,7 @@ function judgeRemoteInitial(bytes, budgetKb, model = COST_MODEL) {
         totalKb,
         limitKb: budgetKb,
         pass: totalKb <= budgetKb,
-        source: 'mfe.json'
+        source: 'mfeflow.app.json'
     };
     const kb = round1(bytes.entryBytes / remote_budget_KB);
     return {
@@ -715,6 +715,7 @@ function redactUrlsIn(text) {
 }
 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 ENV_KEY_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const FILE_HASH = /^sha256-[0-9a-f]{64}$/;
 const REGISTRY_NAMESPACE = /^@[a-z0-9][a-z0-9-]*$/;
 function isCheckoutPath(value) {
@@ -794,7 +795,7 @@ function validateMfeflowProject(value) {
             });
             if (void 0 !== port && !Number.isInteger(port)) c.add(`${at}.port`, 'must be a whole number');
         }
-        if (0 === shells && 'remote' !== repo) c.add('apps', 'needs at least one shell');
+        if (0 === shells && 'remote' !== repo && 'platform' !== 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)){
@@ -815,6 +816,18 @@ function validateMfeflowProject(value) {
         if (!isSafeRelativePath(file)) c.add(at, 'must be a relative path with forward slashes');
         if ('string' != typeof hash || !FILE_HASH.test(hash)) c.add(at, 'must be a hash like "sha256-<64 hex characters>"');
     }
+    const kept = c.object(value, 'kept', '', false);
+    if (kept) for (const [file, hash] of Object.entries(kept)){
+        const at = `kept.${file}`;
+        if (!isSafeRelativePath(file)) c.add(at, 'must be a relative path with forward slashes');
+        if ('string' != typeof hash || !FILE_HASH.test(hash)) c.add(at, 'must be a hash like "sha256-<64 hex characters>"');
+    }
+    const envKeys = c.object(value, 'envKeys', '', false);
+    if (envKeys) for (const [file, keys] of Object.entries(envKeys)){
+        const at = `envKeys.${file}`;
+        if (!isSafeRelativePath(file)) c.add(at, 'must be a relative path with forward slashes');
+        if (!Array.isArray(keys) || keys.some((key)=>'string' != typeof key || !ENV_KEY_NAME.test(key))) c.add(at, 'must be a list of key names like "API_ORIGIN"');
+    }
     const registries = c.object(value, 'registries', '', false);
     if (registries) for (const [ns, url] of Object.entries(registries)){
         const at = `registries.${ns}`;
@@ -1148,13 +1161,16 @@ function isFeatureManifest(value) {
 }
 const DOCS_URL = 'https://mfeflow.github.io/mfeflow';
 const SCHEMA_URLS = {
-    mfe: `${DOCS_URL}/schema/mfe.json`,
+    mfe: `${DOCS_URL}/schema/mfeflow-app.json`,
     project: `${DOCS_URL}/schema/mfeflow.json`,
     feature: `${DOCS_URL}/schema/feature.json`,
     registryEntry: `${DOCS_URL}/schema/registry-entry.json`,
     registryIndex: `${DOCS_URL}/schema/registry-index.json`,
     featureRegistryIndex: `${DOCS_URL}/schema/feature-registry-index.json`
 };
+const SCHEMA_ALIASES = {
+    [`${DOCS_URL}/schema/mfe.json`]: 'mfe'
+};
 function errorDocsUrl(code) {
     return `${DOCS_URL}/errors/${code}`;
 }
@@ -1394,7 +1410,7 @@ const json_schema_item = (properties, required)=>({
         required
     });
 const JSON_SCHEMAS = {
-    mfe: root('mfe', 'mfe.json', {
+    mfe: root('mfe', 'mfeflow.app.json', {
         properties: {
             name: str(MFE_NAME),
             owner: str(),
@@ -1510,6 +1526,16 @@ const JSON_SCHEMAS = {
                 propertyNames: relativePath,
                 additionalProperties: str(FILE_HASH)
             },
+            kept: {
+                type: 'object',
+                propertyNames: relativePath,
+                additionalProperties: str(FILE_HASH)
+            },
+            envKeys: {
+                type: 'object',
+                propertyNames: relativePath,
+                additionalProperties: json_schema_strings(ENV_KEY_NAME)
+            },
             registries: {
                 type: 'object',
                 propertyNames: {
@@ -1759,4 +1785,4 @@ const JSON_SCHEMAS = {
     })
 };
 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 };
+export { ANALYTICS_EVENT, COST_MODEL, DOCS_URL, ENV_KEY_NAME, 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_ALIASES, 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,7 +1,7 @@
 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. */
+/** `mfeflow.app.json` (formerly `mfe.json`): who owns a micro-frontend and what it promises. */
 export interface MfeManifest {
     $schema?: string;
     /** Module Federation name: lowercase letters, digits, `_`. */

package/dist/project.d.ts

@@ -5,7 +5,7 @@ export interface MfeflowProject {
     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. */
+    /** Which repo this is in a multi-repo setup. Absent means a monorepo. A `platform` or `remote` repo may have no shell. */
     repo?: 'platform' | 'shell' | 'remote';
     topology: 'monorepo' | 'polyrepo' | 'hybrid';
     packageManager: 'pnpm' | 'npm';
@@ -24,6 +24,16 @@ export interface MfeflowProject {
     }>;
     /** Hashes of copied files, so `upgrade` can tell when a file was edited. */
     files?: Record<string, string>;
+    /**
+     * Files `upgrade --keep` left alone: the hash of the new version each one was kept against.
+     * While the new version is that one, the file stays quiet; when it changes, the file is raised again.
+     */
+    kept?: Record<string, string>;
+    /**
+     * Keys `mfeflow add env-key` wrote, by the file it wrote them in. `upgrade` asks before a new
+     * template changes the value of one of them. Absent in projects made before this was recorded.
+     */
+    envKeys?: Record<string, string[]>;
     /** Third-party feature registries: `{ "@someone": "https://…/{name}.json" }`, https only (plain http for loopback hosts). `@mfeflow` is reserved. */
     registries?: Record<string, string>;
     /** Built mfeflow checkout, relative to the project root, that `@mfeflow/*` dependencies link to. Set by `--local` only. */
@@ -51,6 +61,8 @@ export interface ProjectBudget {
 }
 /** The regex form of `isCheckoutPath`, for JSON Schema. */
 export declare const CHECKOUT_PATH: RegExp;
+/** An env key name, as `mfeflow add env-key` accepts it. */
+export declare const ENV_KEY_NAME: 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. */

package/dist/remote-budget.d.ts

@@ -2,17 +2,17 @@ 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. */
+    /** Gzip KB that were judged, one decimal: the entry plus the primary expose, or the entry alone without an app file 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';
+    /** Where the limit came from: the remote's `mfeflow.app.json` budget or the cost model. */
+    source: 'mfeflow.app.json' | 'cost-model';
 }
 /**
- * Judges the JS a remote loads first. With an `mfe.json` `budgets.initialJsKb` the entry plus the
+ * Judges the JS a remote loads first. With a `mfeflow.app.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: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mfeflow/contracts",
-  "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).",
+  "version": "0.7.0",
+  "description": "Types, validators and JSON Schemas for mfeflow: mfeflow.app.json ownership manifests, mfeflow.json project state, and the remote registry (entries and index).",
   "keywords": [
     "micro-frontend",
     "mfe",