@mfeflow/core 0.4.0 → 0.5.0

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 /**
  * Every error the engine throws. Ranges: E1xx project and config, E2xx
- * features, E3xx build and runtime, E4xx registry, E5xx upgrade.
+ * features, E3xx build and runtime, E4xx feature registries, E5xx deploy and the static registry.
  */
 export declare const ERROR_CATALOGUE: {
     readonly E101: {
@@ -64,8 +64,8 @@ export declare const ERROR_CATALOGUE: {
         readonly fix: 'Give one of them another port in its rsbuild config and in "apps" in mfeflow.json.';
     };
     readonly E116: {
-        readonly title: 'Two remotes claim the same route, or an mfe.json disagrees with mfeflow.json';
-        readonly fix: 'Give each route to one remote, and keep the name in mfe.json equal to the app name.';
+        readonly title: 'Two remotes claim routes that overlap, or an mfe.json disagrees with mfeflow.json';
+        readonly fix: 'Give each route to one remote (a wildcard such as /checkout/* also covers /checkout/pay), and keep the name in mfe.json equal to the app name.';
     };
     readonly E117: {
         readonly title: 'A copied file changed since mfeflow wrote it';
@@ -187,6 +187,62 @@ export declare const ERROR_CATALOGUE: {
         readonly title: 'A feature in the registry folder cannot be published';
         readonly fix: 'Fix the features listed above. They are checked with the same rules `mfeflow add @namespace/name` applies, so a feature that passes here installs for users.';
     };
+    readonly E501: {
+        readonly title: 'A deploy failed the schema gate';
+        readonly fix: "Fix what the message names: the remote's mfe.json, its mf-manifest.json or the version. Nothing was uploaded. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E502: {
+        readonly title: 'A route of this remote overlaps a route of another remote';
+        readonly fix: "Give each URL to one remote (/checkout/* also covers /checkout/pay), then deploy again. Nothing was uploaded. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E503: {
+        readonly title: "The remote's shared ranges do not fit the shell that is deployed";
+        readonly fix: "Align the remote with the shell on the package named above, or deploy the shell first. Nothing was uploaded. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E504: {
+        readonly title: 'The remote is over its first-load JS budget';
+        readonly fix: "Cut what the remote loads first, or raise budgets.initialJsKb in its mfe.json on purpose. Nothing was uploaded. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E505: {
+        readonly title: 'A rollout was asked for, and a static host cannot split traffic';
+        readonly fix: "Deploy to one version at a time, or use the registry server for percentage rollouts. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E506: {
+        readonly title: 'The registry host is not set up or cannot be used';
+        readonly fix: "Pass --host file:<dir> or s3://<bucket>[/prefix], or set registry.host in mfeflow.json. Deploys also need --base-url or registry.baseUrl. S3 settings come from MFEFLOW_S3_ENDPOINT, MFEFLOW_S3_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E507: {
+        readonly title: 'There is no build output to deploy';
+        readonly fix: "Run `pnpm build` in the remote first. The build folder needs an mf-manifest.json, and the remote needs a version in package.json or --version. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E508: {
+        readonly title: 'There is no such version to move to';
+        readonly fix: "Run `mfeflow status` to see what each environment serves and the versions you can go back to. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E509: {
+        readonly title: 'Files of the target version are missing on the host';
+        readonly fix: "Deploy that version again from its build, or pick another version with --to. The index was not changed. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E510: {
+        readonly title: 'Another deploy changed the index at the same time';
+        readonly fix: "Run `mfeflow status` to see what is served now, then run the command again. The index was not changed by this run. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E511: {
+        readonly title: 'This version is already published with different content';
+        readonly fix: "A published version never changes. Bump the version and deploy again. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E512: {
+        readonly title: 'Local registry files and the host disagree';
+        readonly fix: "Run the deploy, promote or rollback that was meant to move the environment, or fix registry/envs by hand. Artifacts uploaded with --no-publish are not served until you deploy them. See https://mfeflow.github.io/mfeflow/guide/deploy-and-rollback.";
+    };
+    readonly E405: {
+        readonly title: 'The registry is not trusted yet';
+        readonly fix: 'Run `mfeflow registry trust @namespace` once to allow requests to it, or remove it from "registries".';
+    };
+    readonly E406: {
+        readonly title: 'The registry changed a feature since you added it';
+        readonly fix: 'Nothing was written. Look at what changed; if you accept the new content, run the command again with --accept-changed-content.';
+    };
 };
 export type ErrorCode = keyof typeof ERROR_CATALOGUE;
 export interface MfeflowErrorOptions {

package/dist/features/index.d.ts

@@ -1,5 +1,6 @@
 export { listLocalFeatures, loadFeature, parseFeature, type LoadedFeature, type LoadOptions, } from './load.js';
-export { fetchFeatureIndex, fetchRemoteText, getHttps, readCappedText, registryUrl, type FetchLike, type FetchResponse, } from './remote.js';
+export { fetchFeatureIndex, fetchRemoteText, getHttps, checkIntegrity, indexedVersion, integrityOf, readCappedText, registryUrl, type FetchLike, type FetchResponse, } from './remote.js';
+export { addTrusted, configDirOf, parseTrustEnv, readTrusted, removeTrusted, TRUST_ENV, trustedNamespaces, trustFileIn, type EnvTrust, type Trusted, type TrustedRegistry, } from './trust.js';
 export { resolveFeature, resolveOptions, type ResolveInput } from './resolve.js';
 export { type Trust } from './policy.js';
 export { isProtectedPath } from './write-policy.js';

package/dist/features/load.d.ts

@@ -7,6 +7,8 @@ export interface LoadedFeature {
     trust: Trust;
     /** Reads a `from` file of a local feature. Absent for remote features. */
     readAsset?: (relative: string) => Promise<string>;
+    /** `sha256-<hex>` of the feature.json a registry served. Absent for local features. */
+    integrity?: string;
 }
 /** Parses and checks the text of a `feature.json`. Third-party manifests also pass the declarative-only policy. */
 export declare function parseFeature(text: string, trust: Trust, label: string): FeatureManifest;
@@ -19,6 +21,10 @@ export interface LoadOptions {
     /** The version to ask a registry for, when its URL template has `{version}`. */
     version?: string;
     fs?: FsOps;
+    /** The user trusts this feature's registry, so it may be on a loopback or private address. */
+    trusted?: boolean;
+    /** Also compare the version the registry's index lists with the one in the feature.json (E402 on a difference). */
+    checkIndex?: boolean;
 }
 /**
  * Finds a feature by name. `@ns/name` comes from that namespace's registry and

package/dist/features/remote.d.ts

@@ -26,13 +26,24 @@ export declare function registryUrl(name: string, registries: Record<string, str
  * GETs `url`, following redirects by hand so one that leaves https is refused before it is
  * requested. `code` is the error every failure here throws. With `loopback`, a URL that starts
  * on plain http at 127.0.0.1, localhost or [::1] may stay on such a host; nothing else may
- * step down to http, and an https URL never ends up on one.
+ * step down to http, and an https URL never ends up on one. With `blockPrivate`, no request goes
+ * to a loopback or private address (`isPrivateHost`), not even by redirect; that is E405. With
+ * `blockPrivate: false` (a trusted registry) a private address is fine only when `url` itself is
+ * private, so a public server can never redirect you into a private network.
  */
 export declare function getHttps(url: string, fetchImpl: FetchLike, code: 'E109' | 'E401', options?: {
     loopback?: boolean;
+    blockPrivate?: boolean;
 }): Promise<FetchResponse>;
 /** Downloads the feature.json text for `@ns/name`. */
-export declare function fetchRemoteText(name: string, registries: Record<string, string>, fetchImpl?: FetchLike, version?: string): Promise<string>;
+export declare function fetchRemoteText(name: string, registries: Record<string, string>, fetchImpl?: FetchLike, version?: string, trusted?: boolean): Promise<string>;
+/**
+ * Compares the hash recorded when `name` was added with the one of what the registry serves now.
+ * A difference is an E406 unless `accept`; returns whether the content changed.
+ */
+export declare function checkIntegrity(name: string, recorded: string, served: string, accept: boolean): boolean;
+/** `sha256-<hex>` of the exact text a registry served. */
+export declare function integrityOf(text: string): string;
 /**
  * The body of `response` as text, refusing more than `maxBytes`: from the declared
  * length first, then on the bytes actually streamed, so an oversized answer is
@@ -44,4 +55,9 @@ export declare function readCappedText(response: FetchResponse, maxBytes: number
  * template starts in (see `registryIndexUrl`). Fails with E401 when it cannot be fetched and E403
  * when it is not an index, so a caller can show one registry's problem and carry on with the rest.
  */
-export declare function fetchFeatureIndex(namespace: string, registries: Record<string, string>, fetchImpl?: FetchLike): Promise<FeatureRegistryItem[]>;
+export declare function fetchFeatureIndex(namespace: string, registries: Record<string, string>, fetchImpl?: FetchLike, trusted?: boolean): Promise<FeatureRegistryItem[]>;
+/**
+ * The version `<namespace>`'s index lists for the bare feature `name`, undefined when the index
+ * does not list it or the registry has none (404). Any other failure to read it is thrown.
+ */
+export declare function indexedVersion(namespace: string, name: string, registries: Record<string, string>, fetchImpl?: FetchLike, trusted?: boolean): Promise<string | undefined>;

package/dist/features/trust.d.ts

@@ -0,0 +1,44 @@
+import { type FsOps } from '../fs.js';
+/** A registry the user has accepted: this namespace at exactly this URL template. */
+export interface TrustedRegistry {
+    namespace: string;
+    template: string;
+}
+export declare const TRUST_FILE = "trusted-registries.json";
+/** Names the namespaces to trust for one run without touching the trust file, like `@a,@b`. For CI. */
+export declare const TRUST_ENV = "MFEFLOW_TRUST_REGISTRIES";
+/**
+ * Where mfeflow keeps per-user settings: `MFEFLOW_CONFIG_DIR`, else `$XDG_CONFIG_HOME/mfeflow`,
+ * else `%APPDATA%\mfeflow` on Windows, else `~/.config/mfeflow`.
+ */
+export declare function configDirOf(env: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, home?: string): string;
+export declare function trustFileIn(configDir: string): string;
+/**
+ * What the user has trusted. A missing, unreadable or malformed file trusts nothing, so a damaged
+ * file fails closed and the next `registry trust` replaces it.
+ */
+export declare function readTrusted(configDir: string, ops?: FsOps): Promise<TrustedRegistry[]>;
+/** Records `entry`. Returns false when it was already trusted. */
+export declare function addTrusted(configDir: string, entry: TrustedRegistry, ops?: FsOps): Promise<boolean>;
+/** Forgets everything trusted under `namespace`. Returns how many entries went. */
+export declare function removeTrusted(configDir: string, namespace: string, ops?: FsOps): Promise<number>;
+/** One item of `TRUST_ENV`: a namespace, optionally pinned to the URL template it must have. */
+export interface EnvTrust {
+    namespace: string;
+    template?: string;
+}
+/** Reads `@a,@b=https://host/{name}.json`: items split on commas, anything that is not a namespace dropped. */
+export declare function parseTrustEnv(value: string | undefined): EnvTrust[];
+export interface Trusted {
+    /** Registries that may be asked at all. */
+    fetch: Set<string>;
+    /** Registries that may also be on a loopback or private address. */
+    privateOk: Set<string>;
+}
+/**
+ * What the user trusts among `registries`. The trust file and a pinned env item (`@ns=<template>`
+ * with the template the project has) allow everything; an env item with only a namespace allows
+ * asking a public registry but never a loopback or private address, so a pull request cannot aim
+ * a CI job at an internal host.
+ */
+export declare function trustedNamespaces(registries: Record<string, string>, recorded: readonly TrustedRegistry[], fromEnv?: readonly EnvTrust[]): Trusted;

package/dist/index.d.ts

@@ -13,4 +13,4 @@ export { applyPlan, type ApplyOptions, type ApplyResult, type InstallContext, ty
 export { renderTemplate, substitute, type TemplateData } from './templates.js';
 export { RUNTIME_CONFIG_FILE, runtimeConfigFiles } from './runtime-config.js';
 export { applyTransform, dotenvKeys, schemaKeys, type SchemaKey } from './transforms/index.js';
-export { buildRegistry, fetchFeatureIndex, fetchRemoteText, isProtectedPath, listLocalFeatures, loadFeature, parseFeature, getHttps, readCappedText, registryUrl, resolveFeature, resolveOptions, type FetchLike, type FetchResponse, type LoadedFeature, type LoadOptions, type RegistryBuild, type RegistryFile, type ResolveInput, type Trust, } from './features/index.js';
+export { buildRegistry, fetchFeatureIndex, fetchRemoteText, isProtectedPath, listLocalFeatures, loadFeature, parseFeature, addTrusted, configDirOf, parseTrustEnv, readTrusted, removeTrusted, TRUST_ENV, trustedNamespaces, trustFileIn, type EnvTrust, type Trusted, type TrustedRegistry, getHttps, checkIntegrity, indexedVersion, integrityOf, readCappedText, registryUrl, resolveFeature, resolveOptions, type FetchLike, type FetchResponse, type LoadedFeature, type LoadOptions, type RegistryBuild, type RegistryFile, type ResolveInput, type Trust, } from './features/index.js';

package/dist/index.js

@@ -1,14 +1,15 @@
 import { createRequire } from "node:module";
-import { FEATURE_CONDITION, FEATURE_NAME, REGISTRY_NAMESPACE, SCHEMA_URLS, TRANSFORM_OPS, errorDocsUrl, isLoopbackHttp, isMfeflowProject, isRegistryProtocol, isSafeRelativePath, registryIndexUrl, registryTemplateProblem, validateFeatureManifest, validateFeatureRegistryIndex, validateMfeflowProject } from "@mfeflow/contracts";
+import { DOCS_URL, FEATURE_CONDITION, FEATURE_NAME, REGISTRY_NAMESPACE, SCHEMA_URLS, TRANSFORM_OPS, errorDocsUrl, isLoopbackHttp, isMfeflowProject, isPrivateHost, isRegistryProtocol, isSafeRelativePath, redactUrl, redactUrlsIn, registryIndexUrl, registryTemplateProblem, validateFeatureManifest, validateFeatureRegistryIndex, validateMfeflowProject } from "@mfeflow/contracts";
 import { createHash } from "node:crypto";
 import promises from "node:fs/promises";
 import node_path from "node:path";
 import { formatPatch, structuredPatch } from "diff";
 import { isMap, isSeq, parseDocument, stringify } from "yaml";
+import { valid, validRange } from "semver";
 import { Eta } from "eta";
 import { isArrayExpression, isArrowFunctionExpression, isBooleanLiteral, isCallExpression, isFunctionDeclaration, isFunctionExpression, isIdentifier, isImportDeclaration, isImportDefaultSpecifier, isImportNamespaceSpecifier, isImportSpecifier, isJSXElement, isJSXFragment, isJSXIdentifier, isMemberExpression, isNode, isNullLiteral, isNumericLiteral, isObjectExpression, isObjectProperty, isParenthesizedExpression, isReturnStatement, isStringLiteral, isTSAsExpression, isTSNonNullExpression, isTSSatisfiesExpression, isUnaryExpression, isValidIdentifier, isVariableDeclaration } from "@babel/types";
 import { parse, parseExpression } from "@babel/parser";
-import { valid, validRange } from "semver";
+import node_os from "node:os";
 const ERROR_CATALOGUE = {
     E101: {
         title: 'A shared singleton is missing from the shared list',
@@ -71,8 +72,8 @@ const ERROR_CATALOGUE = {
         fix: 'Give one of them another port in its rsbuild config and in "apps" in mfeflow.json.'
     },
     E116: {
-        title: 'Two remotes claim the same route, or an mfe.json disagrees with mfeflow.json',
-        fix: 'Give each route to one remote, and keep the name in mfe.json equal to the app name.'
+        title: 'Two remotes claim routes that overlap, or an mfe.json disagrees with mfeflow.json',
+        fix: 'Give each route to one remote (a wildcard such as /checkout/* also covers /checkout/pay), and keep the name in mfe.json equal to the app name.'
     },
     E117: {
         title: 'A copied file changed since mfeflow wrote it',
@@ -193,6 +194,62 @@ const ERROR_CATALOGUE = {
     E404: {
         title: 'A feature in the registry folder cannot be published',
         fix: 'Fix the features listed above. They are checked with the same rules `mfeflow add @namespace/name` applies, so a feature that passes here installs for users.'
+    },
+    E501: {
+        title: 'A deploy failed the schema gate',
+        fix: `Fix what the message names: the remote's mfe.json, its mf-manifest.json or the version. Nothing was uploaded. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E502: {
+        title: 'A route of this remote overlaps a route of another remote',
+        fix: `Give each URL to one remote (/checkout/* also covers /checkout/pay), then deploy again. Nothing was uploaded. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E503: {
+        title: "The remote's shared ranges do not fit the shell that is deployed",
+        fix: `Align the remote with the shell on the package named above, or deploy the shell first. Nothing was uploaded. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E504: {
+        title: 'The remote is over its first-load JS budget',
+        fix: `Cut what the remote loads first, or raise budgets.initialJsKb in its mfe.json on purpose. Nothing was uploaded. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E505: {
+        title: 'A rollout was asked for, and a static host cannot split traffic',
+        fix: `Deploy to one version at a time, or use the registry server for percentage rollouts. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E506: {
+        title: 'The registry host is not set up or cannot be used',
+        fix: `Pass --host file:<dir> or s3://<bucket>[/prefix], or set registry.host in mfeflow.json. Deploys also need --base-url or registry.baseUrl. S3 settings come from MFEFLOW_S3_ENDPOINT, MFEFLOW_S3_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E507: {
+        title: 'There is no build output to deploy',
+        fix: `Run \`pnpm build\` in the remote first. The build folder needs an mf-manifest.json, and the remote needs a version in package.json or --version. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E508: {
+        title: 'There is no such version to move to',
+        fix: `Run \`mfeflow status\` to see what each environment serves and the versions you can go back to. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E509: {
+        title: 'Files of the target version are missing on the host',
+        fix: `Deploy that version again from its build, or pick another version with --to. The index was not changed. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E510: {
+        title: 'Another deploy changed the index at the same time',
+        fix: `Run \`mfeflow status\` to see what is served now, then run the command again. The index was not changed by this run. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E511: {
+        title: 'This version is already published with different content',
+        fix: `A published version never changes. Bump the version and deploy again. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E512: {
+        title: 'Local registry files and the host disagree',
+        fix: `Run the deploy, promote or rollback that was meant to move the environment, or fix registry/envs by hand. Artifacts uploaded with --no-publish are not served until you deploy them. See ${DOCS_URL}/guide/deploy-and-rollback.`
+    },
+    E405: {
+        title: 'The registry is not trusted yet',
+        fix: 'Run `mfeflow registry trust @namespace` once to allow requests to it, or remove it from "registries".'
+    },
+    E406: {
+        title: 'The registry changed a feature since you added it',
+        fix: 'Nothing was written. Look at what changed; if you accept the new content, run the command again with --accept-changed-content.'
     }
 };
 class MfeflowError extends Error {
@@ -367,11 +424,14 @@ function recordPlan(project, plan) {
     const features = {
         ...project.features
     };
-    for (const f of plan.features)features[f.name] = f.options ? {
+    for (const f of plan.features)features[f.name] = {
         version: f.version,
-        options: f.options
-    } : {
-        version: f.version
+        ...f.options ? {
+            options: f.options
+        } : {},
+        ...void 0 === f.integrity ? {} : {
+            integrity: f.integrity
+        }
     };
     const next = {
         ...project,
@@ -431,6 +491,11 @@ function emptyPlan() {
     };
 }
 const WORKSPACE_FILE = 'pnpm-workspace.yaml';
+const DEPENDENCY_SECTIONS = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies'
+];
 class PlanBuilder {
     read;
     options;
@@ -499,6 +564,13 @@ class PlanBuilder {
         this.touch(entry);
         entry.current = edit(entry.current);
     }
+    async replace(file, content) {
+        const entry = await this.open(file);
+        if (null === entry.current) throw new MfeflowError('E208', `${file} does not exist`);
+        if ('third-party' === this.trust && entry.current !== content) throw new MfeflowError('E207', file);
+        this.touch(entry);
+        entry.current = content;
+    }
     async delete(file) {
         const entry = await this.open(file);
         this.touch(entry);
@@ -527,9 +599,69 @@ class PlanBuilder {
             file,
             name,
             range: wanted,
-            dev
+            dev,
+            ...'third-party' === this.trust ? {
+                thirdParty: true
+            } : {}
         });
     }
+    async setRange(file, name, range) {
+        if (!isRegistryRange(range)) throw new MfeflowError('E202', `${name}: "${range}" is not a semver range or a dist-tag`);
+        const source = await this.content(file);
+        if (void 0 === source) throw new MfeflowError('E208', `${file} does not exist`);
+        const existing = this.declaredRange(file, source, name);
+        if (existing === range || existing.startsWith('workspace:')) return;
+        if (!existing.startsWith('catalog:') && !isRegistryRange(existing)) return void this.warn(`${file}: ${name} is ${JSON.stringify(existing)}; left as it is, not moved to ${range}`);
+        if ('third-party' === this.trust) throw new MfeflowError('E207', `${file}: ${name} is already ${JSON.stringify(existing)}; the feature wants ${range}`);
+        if (existing.startsWith('catalog:')) return void await this.setCatalogEntry(name, existing.slice(8), range);
+        await this.patch(file, (text)=>editJsonObject(file, text, (pkg)=>{
+                const section = DEPENDENCY_SECTIONS.find((key)=>name in asRecord(pkg[key])) ?? '';
+                pkg[section] = {
+                    ...asRecord(pkg[section]),
+                    [name]: range
+                };
+                return true;
+            }));
+    }
+    declaredRange(file, source, name) {
+        const pkg = parseJsonObject(file, source);
+        for (const section of DEPENDENCY_SECTIONS){
+            const value = asRecord(pkg[section])[name];
+            if ('string' == typeof value) return value;
+        }
+        throw new MfeflowError('E208', `${file} does not depend on ${name}`);
+    }
+    async setCatalogEntry(name, catalogName, range) {
+        const path = '' === catalogName || 'default' === catalogName ? [
+            'catalog'
+        ] : [
+            'catalogs',
+            catalogName
+        ];
+        const source = await this.content(WORKSPACE_FILE);
+        const doc = void 0 === source ? void 0 : parseDocument(source);
+        const problem = doc?.errors[0];
+        if (problem) throw new MfeflowError('E208', `${WORKSPACE_FILE} is not valid YAML (${problem.message})`, {
+            cause: problem
+        });
+        if (void 0 === doc || !isMap(doc.getIn(path)) || !doc.hasIn([
+            ...path,
+            name
+        ])) throw new MfeflowError('E208', `${WORKSPACE_FILE} has no catalog entry for ${name}`);
+        doc.setIn([
+            ...path,
+            name
+        ], range);
+        let text;
+        try {
+            text = doc.toString();
+        } catch (error) {
+            throw new MfeflowError('E208', `${WORKSPACE_FILE} could not be written back (${messageOf(error)})`, {
+                cause: error
+            });
+        }
+        await this.patch(WORKSPACE_FILE, ()=>text);
+    }
     async addScript(file, name, command) {
         let added = true;
         await this.patch(file, (source)=>editJsonObject(file, source, (pkg)=>{
@@ -600,6 +732,10 @@ class PlanBuilder {
         };
     }
 }
+function isRegistryRange(range) {
+    if ('' === range || range !== range.trim() || range.includes('/')) return false;
+    return /^[a-z][a-z0-9-]*$/.test(range) || null !== validRange(range);
+}
 function isPinnedElsewhere(range) {
     return range.startsWith('catalog:') || range.startsWith('workspace:');
 }
@@ -625,16 +761,20 @@ const VERB = {
     patch: 'patch ',
     delete: 'delete'
 };
+const dependencyLine = (d)=>`  ${d.file}  ${d.name}@${d.range}${d.dev ? ' (dev)' : ''}`;
 function summarize(plan) {
     const count = (action)=>plan.changes.filter((c)=>c.action === action).length;
     const lines = [
         `${String(count('create'))} to create, ${String(count('patch'))} to patch, ${String(count('delete'))} to delete`
     ];
     for (const c of plan.changes)lines.push(`  ${VERB[c.action]}  ${c.path}`);
-    if (plan.dependencies.length > 0) {
-        lines.push(`Dependencies (${String(plan.dependencies.length)}):`);
-        for (const d of plan.dependencies)lines.push(`  ${d.file}  ${d.name}@${d.range}${d.dev ? ' (dev)' : ''}`);
+    const dependencies = plan.dependencies.filter((d)=>true !== d.thirdParty);
+    const newPackages = plan.dependencies.filter((d)=>true === d.thirdParty);
+    if (dependencies.length > 0) {
+        lines.push(`Dependencies (${String(dependencies.length)}):`);
+        for (const d of dependencies)lines.push(dependencyLine(d));
     }
+    if (newPackages.length > 0) lines.push('', `NEW PACKAGES from a third-party feature (${String(newPackages.length)}):`, ...newPackages.map(dependencyLine), "  Check each one before you install. npm and yarn run a package's install scripts;", '  pnpm 10 and later blocks them until you allow them.', '');
     if (plan.scripts.length > 0) {
         lines.push(`Scripts added to package.json, not run (${String(plan.scripts.length)}):`);
         for (const s of plan.scripts)lines.push(`  ${s.file}  ${s.name}: ${s.command}`);
@@ -1712,19 +1852,27 @@ function registryUrl(name, registries, version) {
     try {
         parsed = new URL(url);
     } catch (error) {
-        throw new MfeflowError('E401', `${namespace} has an invalid URL (${url})`, {
+        throw new MfeflowError('E401', `${namespace} has an invalid URL (${redactUrl(url)})`, {
             cause: error
         });
     }
-    if (!isRegistryProtocol(parsed)) throw new MfeflowError('E401', `${url} is not https (plain http is for 127.0.0.1, localhost and [::1] only)`);
+    if (!isRegistryProtocol(parsed)) throw new MfeflowError('E401', `${redactUrl(url)} is not https (plain http is for 127.0.0.1, localhost and [::1] only)`);
     return parsed.href;
 }
 async function getHttps(url, fetchImpl, code, options = {}) {
     const fail = (at, why, cause)=>{
-        throw new MfeflowError(code, `${at}: ${why}`, void 0 === cause ? {} : {
+        throw new MfeflowError(code, redactUrlsIn(`${at}: ${why}`), void 0 === cause ? {} : {
             cause
         });
     };
+    const startsPrivate = isPrivateHost(new URL(url).hostname);
+    const refusePrivate = (target)=>{
+        if (void 0 === options.blockPrivate || !isPrivateHost(target.hostname)) return;
+        if (!options.blockPrivate && startsPrivate) return;
+        const why = options.blockPrivate ? 'those are only requested from a trusted registry' : 'a public registry may not send you to one';
+        throw new MfeflowError('E405', `${redactUrl(target.href)} is a loopback or private address; ${why}`);
+    };
+    refusePrivate(new URL(url));
     const startsLoopback = true === options.loopback && isLoopbackHttp(new URL(url));
     const permitted = (target)=>'https:' === target.protocol || startsLoopback && isLoopbackHttp(target);
     const addressOk = (address)=>{
@@ -1746,6 +1894,7 @@ async function getHttps(url, fetchImpl, code, options = {}) {
             return fail(current, messageOf(error), error);
         }
         if (void 0 !== response.url && '' !== response.url && !addressOk(response.url)) fail(url, `ended up at ${response.url}, which is not https`);
+        if (void 0 !== response.url && '' !== response.url) refusePrivate(new URL(response.url));
         if (response.status < 300 || response.status >= 400) return response;
         const location = response.headers?.get('location');
         await response.body?.cancel().catch(()=>void 0);
@@ -1757,20 +1906,31 @@ async function getHttps(url, fetchImpl, code, options = {}) {
             return fail(current, 'redirected to a bad address', error);
         }
         if (!permitted(next)) fail(url, `redirected to ${next.href}, which is not https`);
+        refusePrivate(next);
         current = next.href;
     }
     return fail(url, 'redirected too many times');
 }
-async function fetchRemoteText(name, registries, fetchImpl = realFetch, version) {
+async function fetchRemoteText(name, registries, fetchImpl = realFetch, version, trusted = false) {
     const url = registryUrl(name, registries, version);
+    const shown = redactUrl(url);
     const response = await getHttps(url, fetchImpl, 'E401', {
-        loopback: true
+        loopback: true,
+        blockPrivate: !trusted
     });
     if (!response.ok) {
         const hint = 404 === response.status ? `${name} is not in that registry` : void 0;
-        throw new MfeflowError('E401', `${url} answered ${String(response.status)}${hint ? `: ${hint}` : ''}`);
+        throw new MfeflowError('E401', `${shown} answered ${String(response.status)}${hint ? `: ${hint}` : ''}`);
     }
-    return readCappedText(response, MAX_BYTES, ()=>new MfeflowError('E402', `${url} is larger than 1 MB`));
+    return readCappedText(response, MAX_BYTES, ()=>new MfeflowError('E402', `${shown} is larger than 1 MB`));
+}
+function checkIntegrity(name, recorded, served, accept) {
+    if (recorded === served) return false;
+    if (!accept) throw new MfeflowError('E406', `${name} was ${recorded} when you added it and is now ${served}`);
+    return true;
+}
+function integrityOf(text) {
+    return `sha256-${createHash('sha256').update(text, 'utf8').digest('hex')}`;
 }
 async function readCappedText(response, maxBytes, tooBig) {
     const declared = Number(response.headers?.get('content-length') ?? 0 / 0);
@@ -1792,34 +1952,45 @@ async function readCappedText(response, maxBytes, tooBig) {
     }
     return new TextDecoder().decode(Buffer.concat(chunks));
 }
-async function fetchFeatureIndex(namespace, registries, fetchImpl = realFetch) {
+async function fetchFeatureIndex(namespace, registries, fetchImpl = realFetch, trusted = false) {
+    const items = await readIndex(namespace, registries, fetchImpl, trusted, false);
+    return items ?? [];
+}
+async function indexedVersion(namespace, name, registries, fetchImpl = realFetch, trusted = false) {
+    const items = await readIndex(namespace, registries, fetchImpl, trusted, true);
+    return items?.find((item)=>item.name === name)?.version;
+}
+async function readIndex(namespace, registries, fetchImpl, trusted, missingOk) {
     const template = registries[namespace];
     if (void 0 === template) throw new MfeflowError('E210', namespace);
     const problem = registryTemplateProblem(template);
     if (void 0 !== problem) throw new MfeflowError('E401', `${namespace}: ${problem}`);
     const url = registryIndexUrl(template);
+    const shown = redactUrl(url);
     const response = await getHttps(url, fetchImpl, 'E401', {
-        loopback: true
+        loopback: true,
+        blockPrivate: !trusted
     });
     if (!response.ok) {
+        if (missingOk && 404 === response.status) return;
         const hint = 404 === response.status ? ': this registry has no index.json' : '';
-        throw new MfeflowError('E401', `${url} answered ${String(response.status)}${hint}`);
+        throw new MfeflowError('E401', `${shown} answered ${String(response.status)}${hint}`);
     }
-    const text = await readCappedText(response, MAX_BYTES, ()=>new MfeflowError('E403', `${url} is larger than 1 MB`));
+    const text = await readCappedText(response, MAX_BYTES, ()=>new MfeflowError('E403', `${shown} is larger than 1 MB`));
     let value;
     try {
         value = JSON.parse(text);
     } catch (error) {
         const reason = messageOf(error).replaceAll(/\p{Cc}/gu, '?');
-        throw new MfeflowError('E403', `${url} is not JSON (${reason})`, {
+        throw new MfeflowError('E403', `${shown} is not JSON (${reason})`, {
             cause: error
         });
     }
     const issues = validateFeatureRegistryIndex(value);
     if (issues.length > 0) {
-        const shown = issues.slice(0, 3).map((i)=>`${i.path || '(root)'} ${i.message}`);
+        const first = issues.slice(0, 3).map((i)=>`${i.path || '(root)'} ${i.message}`);
         const more = issues.length > 3 ? `; and ${String(issues.length - 3)} more` : '';
-        throw new MfeflowError('E403', `${url}: ${shown.join('; ')}${more}`);
+        throw new MfeflowError('E403', `${shown}: ${first.join('; ')}${more}`);
     }
     return itemsOf(value);
 }
@@ -1948,7 +2119,7 @@ function isModuleSpecifier(value) {
 }
 const DIST_TAG = /^[a-z][a-z0-9-]*$/;
 const TARBALL_NAME = /[.](?:tgz|tar\.gz|tar)$/i;
-function isRegistryRange(range) {
+function policy_isRegistryRange(range) {
     if ('' === range || range !== range.trim()) return false;
     if (range.includes('/') || range.includes('\\')) return false;
     if (range.split(/\s+|\|\|/).some((part)=>TARBALL_NAME.test(part))) return false;
@@ -1992,7 +2163,7 @@ function assertThirdPartyContent(manifest, label) {
     }
     for (const dep of manifest.dependencies ?? []){
         if (dep.name.includes('{{')) throw new MfeflowError('E203', `${label}: ${dep.name} names a package in the project's scope`);
-        if (!isRegistryRange(dep.range)) throw new MfeflowError('E203', `${label}: ${dep.name}@${dep.range} is not a registry version range`);
+        if (!policy_isRegistryRange(dep.range)) throw new MfeflowError('E203', `${label}: ${dep.name}@${dep.range} is not a registry version range`);
     }
     for (const t of manifest.transforms ?? [])assertThirdPartyTransform(t, label);
     for (const script of manifest.scripts ?? [])assertPlainScript(script.name, manifest.name, label);
@@ -2064,14 +2235,28 @@ async function loadLocal(name, options) {
     };
 }
 async function loadRemote(name, options) {
-    const text = await fetchRemoteText(name, options.registries ?? {}, options.fetch, options.version);
+    const registries = options.registries ?? {};
+    const text = await fetchRemoteText(name, registries, options.fetch, options.version, true === options.trusted);
     const manifest = parseFeature(text, 'third-party', name);
     if (manifest.name !== name) throw new MfeflowError('E402', `asked for ${name}, got ${manifest.name}`);
+    if (true === options.checkIndex) await assertIndexAgrees(name, manifest.version, registries, options);
     return {
         manifest,
-        trust: 'third-party'
+        trust: 'third-party',
+        integrity: integrityOf(text)
     };
 }
+async function assertIndexAgrees(name, version, registries, options) {
+    const slash = name.indexOf('/');
+    let listed;
+    try {
+        listed = await indexedVersion(name.slice(0, slash), name.slice(slash + 1), registries, options.fetch, true === options.trusted);
+    } catch (error) {
+        if (error instanceof MfeflowError && 'MFEFLOW_E401' === error.code) return;
+        throw error;
+    }
+    if (void 0 !== listed && listed !== version) throw new MfeflowError('E402', `the index lists ${name} at ${listed} but its feature.json is ${version}`);
+}
 async function listLocalFeatures(featuresDir, ops = realFs) {
     let dirs;
     try {
@@ -2082,6 +2267,104 @@ async function listLocalFeatures(featuresDir, ops = realFs) {
     const checked = await Promise.all(dirs.map(async (dir)=>await readIfExists(ops, node_path.join(featuresDir, dir, 'feature.json')) === void 0 ? void 0 : dir));
     return checked.filter((d)=>void 0 !== d).toSorted((a, b)=>a.localeCompare(b));
 }
+const TRUST_FILE = 'trusted-registries.json';
+const TRUST_ENV = 'MFEFLOW_TRUST_REGISTRIES';
+const set = (value)=>void 0 === value || '' === value ? void 0 : value;
+function configDirOf(env, platform = process.platform, home = node_os.homedir()) {
+    const override = set(env.MFEFLOW_CONFIG_DIR);
+    if (void 0 !== override) return override;
+    const xdg = set(env.XDG_CONFIG_HOME);
+    if (void 0 !== xdg) return node_path.join(xdg, 'mfeflow');
+    const appData = set(env.APPDATA);
+    if ('win32' === platform && void 0 !== appData) return node_path.join(appData, 'mfeflow');
+    return node_path.join(home, '.config', 'mfeflow');
+}
+function trustFileIn(configDir) {
+    return node_path.join(configDir, TRUST_FILE);
+}
+function isEntry(value) {
+    if ('object' != typeof value || null === value) return false;
+    const { namespace, template } = Object.fromEntries(Object.entries(value));
+    return 'string' == typeof namespace && REGISTRY_NAMESPACE.test(namespace) && 'string' == typeof template && void 0 === registryTemplateProblem(template);
+}
+async function readTrusted(configDir, ops = realFs) {
+    let text;
+    try {
+        text = await readIfExists(ops, trustFileIn(configDir));
+    } catch  {
+        return [];
+    }
+    if (void 0 === text) return [];
+    try {
+        const value = JSON.parse(text);
+        if ('object' != typeof value || null === value) return [];
+        const { registries } = Object.fromEntries(Object.entries(value));
+        return Array.isArray(registries) ? registries.filter(isEntry) : [];
+    } catch  {
+        return [];
+    }
+}
+async function save(configDir, entries, ops) {
+    const sorted = entries.toSorted((a, b)=>a.namespace.localeCompare(b.namespace) || a.template.localeCompare(b.template));
+    const body = `${JSON.stringify({
+        version: 1,
+        registries: sorted
+    }, null, 2)}\n`;
+    try {
+        await writeFileAtomic(ops, trustFileIn(configDir), body);
+    } catch (error) {
+        throw new MfeflowError('E106', trustFileIn(configDir), {
+            cause: error
+        });
+    }
+}
+async function addTrusted(configDir, entry, ops = realFs) {
+    const current = await readTrusted(configDir, ops);
+    if (current.some((e)=>e.namespace === entry.namespace && e.template === entry.template)) return false;
+    await save(configDir, [
+        ...current,
+        entry
+    ], ops);
+    return true;
+}
+async function removeTrusted(configDir, namespace, ops = realFs) {
+    const current = await readTrusted(configDir, ops);
+    const kept = current.filter((e)=>e.namespace !== namespace);
+    if (kept.length === current.length) return 0;
+    await save(configDir, kept, ops);
+    return current.length - kept.length;
+}
+function parseTrustEnv(value) {
+    return (value ?? '').split(',').map((part)=>part.trim()).flatMap((part)=>{
+        const eq = part.indexOf('=');
+        const namespace = -1 === eq ? part : part.slice(0, eq).trim();
+        if (!REGISTRY_NAMESPACE.test(namespace)) return [];
+        const template = -1 === eq ? '' : part.slice(eq + 1).trim();
+        return [
+            '' === template ? {
+                namespace
+            } : {
+                namespace,
+                template
+            }
+        ];
+    });
+}
+function trustedNamespaces(registries, recorded, fromEnv = []) {
+    const fetch1 = new Set();
+    const privateOk = new Set();
+    for (const [namespace, template] of Object.entries(registries)){
+        const inFile = recorded.some((e)=>e.namespace === namespace && e.template === template);
+        const items = fromEnv.filter((e)=>e.namespace === namespace);
+        const pinned = items.some((e)=>e.template === template);
+        if (inFile || pinned) privateOk.add(namespace);
+        if (inFile || items.some((e)=>void 0 === e.template || e.template === template)) fetch1.add(namespace);
+    }
+    return {
+        fetch: fetch1,
+        privateOk
+    };
+}
 const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
 function shortHash(text) {
     let hash = 0x811c9dc5;
@@ -2263,7 +2546,10 @@ async function resolveFeature(input) {
         version: manifest.version,
         ...Object.keys(options).length > 0 ? {
             options
-        } : {}
+        } : {},
+        ...void 0 === feature.integrity ? {} : {
+            integrity: feature.integrity
+        }
     });
 }
 async function editFile(builder, file, edit, op) {
@@ -2386,4 +2672,4 @@ function packageInfo() {
         version
     };
 }
-export { ERROR_CATALOGUE, MfeflowError, PROJECT_FILE, PlanBuilder, RUNTIME_CONFIG_FILE, applyPlan, applyTransform, buildRegistry, dotenvKeys, emptyPlan, fetchFeatureIndex, fetchRemoteText, findDiverged, findProjectRoot, getHttps, hasErrno, hashContent, inOrder, isMfeflowError, isProtectedPath, listLocalFeatures, loadFeature, loadProject, messageOf, packageInfo, parseFeature, parseProject, readCappedText, realFs, recordPlan, registryUrl, renderDiff, renderTemplate, resolveFeature, resolveOptions, runtimeConfigFiles, saveProject, schemaKeys, serializeProject, substitute, summarize, writeFileAtomic };
+export { ERROR_CATALOGUE, MfeflowError, PROJECT_FILE, PlanBuilder, RUNTIME_CONFIG_FILE, TRUST_ENV, addTrusted, applyPlan, applyTransform, buildRegistry, checkIntegrity, configDirOf, dotenvKeys, emptyPlan, fetchFeatureIndex, fetchRemoteText, findDiverged, findProjectRoot, getHttps, hasErrno, hashContent, inOrder, indexedVersion, integrityOf, isMfeflowError, isProtectedPath, listLocalFeatures, loadFeature, loadProject, messageOf, packageInfo, parseFeature, parseProject, parseTrustEnv, readCappedText, readTrusted, realFs, recordPlan, registryUrl, removeTrusted, renderDiff, renderTemplate, resolveFeature, resolveOptions, runtimeConfigFiles, saveProject, schemaKeys, serializeProject, substitute, summarize, trustFileIn, trustedNamespaces, writeFileAtomic };

package/dist/plan.d.ts

@@ -17,12 +17,16 @@ export interface PlanFeature {
     name: string;
     version: string;
     options?: Record<string, unknown>;
+    /** `sha256-<hex>` of the feature.json a registry served; recorded in mfeflow.json. */
+    integrity?: string;
 }
 export interface DependencyAdd {
     file: string;
     name: string;
     range: string;
     dev: boolean;
+    /** Added by a third-party feature, so `summarize` lists it in its own block. */
+    thirdParty?: boolean;
 }
 /** Added to package.json and shown. The engine never runs it. */
 export interface ScriptAdd {
@@ -99,8 +103,22 @@ export declare class PlanBuilder {
     create(file: string, content: string, track?: boolean): Promise<void>;
     /** Rewrites an existing file. */
     patch(file: string, edit: (source: string) => string): Promise<void>;
+    /** Overwrites a file that exists, shown as a modification. First-party only: a third-party feature never replaces content. */
+    replace(file: string, content: string): Promise<void>;
     delete(file: string): Promise<void>;
     addDependency(file: string, name: string, range: string, dev?: boolean): Promise<void>;
+    /**
+     * Moves an existing dependency to `range`. A dependency on `catalog:` changes
+     * its entry in pnpm-workspace.yaml instead. A `workspace:` link, or any
+     * specifier that is not a registry range (`npm:`, `link:`, `file:`, a
+     * repository or a URL), is the project's own choice and is left alone with a
+     * warning. The new range must be a semver range or a dist-tag (E202). A
+     * missing dependency is an E208. A third-party feature can only ask for the
+     * range that is already there.
+     */
+    setRange(file: string, name: string, range: string): Promise<void>;
+    private declaredRange;
+    private setCatalogEntry;
     /** Adds a script. An identical one already there is a no-op; a different command under the same name is a conflict. */
     addScript(file: string, name: string, command: string): Promise<void>;
     addEnvKey(file: string, key: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfeflow/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The engine behind the mfeflow CLI: project model, change plans with diffs, atomic apply with rollback, and feature resolution.",
   "keywords": [
     "micro-frontend",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@babel/parser": "8.0.10",
     "@babel/types": "8.0.10",
-    "@mfeflow/contracts": "0.4.0",
+    "@mfeflow/contracts": "0.5.0",
     "diff": "9.0.0",
     "eta": "4.6.0",
     "semver": "7.8.5",