@mfeflow/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @mfeflow/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [mfeflow](https://github.com/mfeflow/mfeflow), the React micro-frontend boilerplate and platform kit.
+
+The engine behind the `mfeflow` CLI: loads and saves `mfeflow.json`, plans a change as data with a unified diff, applies it atomically with rollback, and resolves features. Pre-1.0: minor versions may change the API. Most people want the [`mfeflow`](https://www.npmjs.com/package/mfeflow) CLI instead.
+
+```sh
+pnpm add @mfeflow/core
+```
+
+Docs: [mfeflow.github.io/mfeflow](https://mfeflow.github.io/mfeflow/).
+
+MIT licensed.
+
+## What a third-party feature may do
+
+A feature from a namespaced registry (`@someone/name`) is untrusted. It is
+declarative only and is checked against allowlists when it is loaded and again
+when it is resolved into a plan. It can never cause code to run on apply,
+install, commit or the next `mfeflow` command.
+
+- **Files and transforms** write only under `src/`, `public/` or `docs/` of the
+  target, with plain lower-case ASCII names. Root files, dot folders, package
+  manager config (`package.json`, lockfiles, `.npmrc`, `.yarnrc*`,
+  `.pnpmfile.*`, `pnpm-workspace.yaml`), git hook managers, test and tool config
+  files and the local `features/` folder are refused. Paths are compared after
+  Unicode (NFC) and case folding, and names with trailing dots or spaces, `:`,
+  invisible characters or Windows device names are refused for every feature.
+- **Scripts** are lower-case words joined by `:`. Lifecycle events, `pnpm:`,
+  `npm:`, `yarn:` and `bun:` prefixes and every `pre` or `post` name are refused.
+- **Dependencies** take a semver range or a dist-tag. `file:`, `link:`, git,
+  URLs, `npm:` aliases, `workspace:` and `catalog:` are refused.
+- **Imports** name a package, a relative path or an `@/` alias, never a URL.
+- **`add-env-key`** schema text must be a call chain on `z`, `v` or `type` with
+  literal arguments; the plan writes it re-emitted from the parsed tree. Because
+  `.env.example` and root `env.ts` are outside the allowlist, third parties can
+  add runtime-config keys (under `src/` and `public/`) but not dotenv examples.
+- **`add-workflow-step`** is refused: third-party features cannot edit CI.
+
+For every feature, first-party included: a script or dependency that already
+exists with another value is an E207 conflict in the plan, never an overwrite;
+a first-party CI change shows as a warning in the plan summary; and `applyPlan`
+checks that every target resolves, symlinks included, to inside the project
+before writing anything. Its rollback restores files by temp file and rename,
+and after a failed install it also puts back `package.json`, the workspace file
+and the lockfiles the install touched (`node_modules` is not rolled back).

package/dist/apply.d.ts

@@ -0,0 +1,29 @@
+import { type FsOps } from './fs.js';
+import { type MfeflowProject } from './project.js';
+import type { Plan } from './plan.js';
+export interface InstallContext {
+    root: string;
+    plan: Plan;
+}
+/** Runs the package manager. Injected so tests and `--no-install` never touch the network. */
+export type InstallStep = (context: InstallContext) => Promise<void>;
+export interface ApplyOptions {
+    root: string;
+    /** The project as it is now. When given, `mfeflow.json` is updated in the same transaction. */
+    project?: MfeflowProject;
+    install?: InstallStep;
+    fs?: FsOps;
+    /** Check the plan against the files and stop before writing anything. */
+    dryRun?: boolean;
+}
+export interface ApplyResult {
+    written: string[];
+    project: MfeflowProject | undefined;
+}
+/**
+ * Writes a plan to disk, all or nothing. Every target is checked against what
+ * the plan was made from, new content is staged next to its target and
+ * renamed into place, and on any failure (including the install step) the
+ * originals are put back.
+ */
+export declare function applyPlan(plan: Plan, options: ApplyOptions): Promise<ApplyResult>;

package/dist/errors.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Every error the engine throws. Ranges: E1xx project and config, E2xx
+ * features, E3xx build and runtime, E4xx registry, E5xx upgrade.
+ */
+export declare const ERROR_CATALOGUE: {
+    readonly E101: {
+        readonly title: 'A shared singleton is missing from the shared list';
+        readonly fix: 'Run `mfeflow doctor --fix`, or add the package to the singletons list.';
+    };
+    readonly E102: {
+        readonly title: 'No mfeflow.json found';
+        readonly fix: 'Run the command inside an mfeflow project, pass --cwd, or create one with `npm create mfeflow@latest`.';
+    };
+    readonly E103: {
+        readonly title: 'mfeflow.json is not valid JSON';
+        readonly fix: 'Fix the syntax error, or restore the file from git.';
+    };
+    readonly E104: {
+        readonly title: 'mfeflow.json does not match its schema';
+        readonly fix: "Fix the fields listed above. The schema is at https://mfeflow.github.io/mfeflow/schema/mfeflow.json.";
+    };
+    readonly E105: {
+        readonly title: 'A path points outside the project';
+        readonly fix: 'Use paths relative to the project root, with forward slashes and no "..".';
+    };
+    readonly E106: {
+        readonly title: 'A file could not be read or written';
+        readonly fix: 'Check that the file exists and that you have permission to change it.';
+    };
+    readonly E107: {
+        readonly title: 'A command-line option is missing or not valid';
+        readonly fix: 'Run the command with --help to see the options and examples.';
+    };
+    readonly E108: {
+        readonly title: 'The target folder is not empty';
+        readonly fix: 'Pick a new or empty folder, or move what is in the way.';
+    };
+    readonly E109: {
+        readonly title: 'The preset could not be used';
+        readonly fix: 'Pass a JSON file or an https URL that holds an object of option names and values.';
+    };
+    readonly E110: {
+        readonly title: '--local does not point at a built mfeflow checkout';
+        readonly fix: 'Pass the folder of a mfeflow/mfeflow clone where `pnpm install && pnpm build` has run.';
+    };
+    readonly E111: {
+        readonly title: 'A workspace package has no version';
+        readonly fix: 'Add a "version" to its package.json (`mfeflow doctor --fix` writes 0.0.0). Without one Module Federation never shares the package and each app loads its own copy.';
+    };
+    readonly E112: {
+        readonly title: 'An app in mfeflow.json is not on disk';
+        readonly fix: 'Restore the folder, or remove the app from "apps" in mfeflow.json.';
+    };
+    readonly E113: {
+        readonly title: 'mfe.json is missing or invalid';
+        readonly fix: "Give the app a valid mfe.json (name, owner, shells, routes, exposes). The schema is at https://mfeflow.github.io/mfeflow/schema/mfe.json.";
+    };
+    readonly E114: {
+        readonly title: 'A registry entry is missing or invalid';
+        readonly fix: "Every remote needs registry/envs/<env>/<name>.json for dev, staging and prod (`mfeflow doctor --fix` writes the missing ones). The schema is at https://mfeflow.github.io/mfeflow/schema/registry-entry.json.";
+    };
+    readonly E115: {
+        readonly title: 'Two apps use the same port';
+        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 E117: {
+        readonly title: 'A copied file changed since mfeflow wrote it';
+        readonly fix: 'Nothing is wrong if you changed it on purpose. `mfeflow upgrade` will show a diff before touching it.';
+    };
+    readonly E118: {
+        readonly title: '.env.example does not match the keys in env.ts';
+        readonly fix: 'List every key of the `server` schema in .env.example (`mfeflow add env-key KEY --scope server --schema "…"` keeps them together) and remove the ones env.ts no longer has.';
+    };
+    readonly E119: {
+        readonly title: 'A runtime-config file does not match the runtime-config schema';
+        readonly fix: 'Give every runtime-config.<env>.json the keys of src/config/schema.ts and nothing else, then run `pnpm check:runtime-config` to validate the values.';
+    };
+    readonly E120: {
+        readonly title: 'A PUBLIC_ variable would be baked into the bundle';
+        readonly fix: 'PUBLIC_* values are inlined at build time, so one build could no longer run in every environment. Put per-environment values in runtime-config.<env>.json instead (`mfeflow add env-key KEY --scope runtime --schema "…"`). PUBLIC_APP_NAME and PUBLIC_BUILD_VERSION are fine.';
+    };
+    readonly E121: {
+        readonly title: 'A server env key is not listed in turbo.json';
+        readonly fix: 'Add the key to "globalEnv" in turbo.json. Turborepo hides unlisted variables from tasks and replays a cached build without running env.ts, so a missing value would not fail the build.';
+    };
+    readonly E201: {
+        readonly title: 'Feature not found';
+        readonly fix: 'List what is available with `mfeflow features`, or check the spelling.';
+    };
+    readonly E202: {
+        readonly title: 'feature.json is invalid';
+        readonly fix: "Fix the fields listed above. The schema is at https://mfeflow.github.io/mfeflow/schema/feature.json.";
+    };
+    readonly E203: {
+        readonly title: 'A third-party feature uses something third-party features may not';
+        readonly fix: 'Third-party features are declarative: files under src/, public/ and docs/, registry dependencies, plain script names and the built-in transform ops (not add-workflow-step). Ask the author to remove it, or do not add this feature.';
+    };
+    readonly E204: {
+        readonly title: 'Unknown transform op';
+        readonly fix: 'Built-in ops: add-import, wrap-provider, add-shared, add-boot-step, add-env-key, add-route, add-workflow-step. If you need another, open an issue.';
+    };
+    readonly E205: {
+        readonly title: 'Feature conflicts with an installed feature';
+        readonly fix: 'Remove the conflicting feature first, or pick one of the two.';
+    };
+    readonly E206: {
+        readonly title: 'Feature needs another feature first';
+        readonly fix: 'Add the required feature in the same command, for example `mfeflow add tsconfig this-feature`.';
+    };
+    readonly E207: {
+        readonly title: 'The feature wants to create or change something that already exists';
+        readonly fix: 'Move or delete the existing file, script or dependency range, or edit it by hand and skip that part of the feature.';
+    };
+    readonly E208: {
+        readonly title: 'A file the feature edits is missing or not shaped as expected';
+        readonly fix: 'Restore the file from the template, or apply the change by hand using the diff.';
+    };
+    readonly E209: {
+        readonly title: 'A template could not be rendered';
+        readonly fix: 'Check the template for typos and that every option it uses is defined.';
+    };
+    readonly E210: {
+        readonly title: 'Registry namespace is not configured';
+        readonly fix: 'Add it to "registries" in mfeflow.json, for example { "@someone": "https://example.com/{name}.json" }.';
+    };
+    readonly E211: {
+        readonly title: 'Files changed since the plan was made';
+        readonly fix: 'Nothing was written. Run the command again to plan against the current files.';
+    };
+    readonly E212: {
+        readonly title: 'Applying the plan failed';
+        readonly fix: 'Everything already written was rolled back. Fix the cause above and run the command again.';
+    };
+    readonly E213: {
+        readonly title: 'Installing dependencies failed';
+        readonly fix: 'The files the plan wrote, and any package.json, lockfile or workspace file the install changed, were restored. node_modules is not rolled back, so run your package manager install once. Then check your network and package manager and run the command again.';
+    };
+    readonly E214: {
+        readonly title: 'A feature option is invalid';
+        readonly fix: 'Pass a value the feature accepts; `mfeflow features <name>` lists the options.';
+    };
+    readonly E215: {
+        readonly title: 'The app name cannot be used';
+        readonly fix: 'Use lowercase words of letters and digits joined by single underscores (order_history), starting with a letter, and a name no app has yet.';
+    };
+    readonly E301: {
+        readonly title: 'A singleton resolves to more than one version';
+        readonly fix: 'Pin one version of the package in every app (the pnpm catalog is the place), then reinstall. Two copies of React break hooks.';
+    };
+    readonly E302: {
+        readonly title: 'A remote is not compatible with its shell';
+        readonly fix: 'Align the remote and the shell on the same major of the package, or update the "platform" range in the remote\'s mfe.json.';
+    };
+    readonly E303: {
+        readonly title: 'A runtime plugin imports a shared module';
+        readonly fix: 'Runtime plugins run before the share scope exists. Keep them dependency free and report through `window`.';
+    };
+    readonly E304: {
+        readonly title: 'A bundle is over its budget';
+        readonly fix: 'Cut what the app ships on first load, or raise the budget in mfeflow.json ("budget") or mfe.json ("budgets") on purpose.';
+    };
+    readonly E305: {
+        readonly title: 'There is no build output to measure';
+        readonly fix: 'Run `pnpm build` first.';
+    };
+    readonly E306: {
+        readonly title: 'A dev server could not start';
+        readonly fix: "Free the port or change it in mfeflow.json and the app's rsbuild config, then run `mfeflow dev` again.";
+    };
+    readonly E401: {
+        readonly title: 'Could not fetch from the registry';
+        readonly fix: 'Check the URL in "registries" and your network, then try again.';
+    };
+    readonly E402: {
+        readonly title: 'The registry returned something that is not a feature';
+        readonly fix: 'Ask the registry owner to check the entry. It must be a feature.json document.';
+    };
+};
+export type ErrorCode = keyof typeof ERROR_CATALOGUE;
+export interface MfeflowErrorOptions {
+    cause?: unknown;
+    /** Replaces the catalogue's fix when the situation has a more specific one. */
+    fix?: string;
+}
+/** An error with a stable code, a fix hint and a docs link. */
+export declare class MfeflowError extends Error {
+    readonly code: `MFEFLOW_${ErrorCode}`;
+    readonly fix: string;
+    readonly docs: string;
+    constructor(code: ErrorCode, detail?: string, options?: MfeflowErrorOptions);
+    /** The three-line form the CLI prints. */
+    format(): string;
+}
+export declare function isMfeflowError(value: unknown): value is MfeflowError;
+/** Message of anything thrown, for error details. */
+export declare function messageOf(error: unknown): string;
+/** True for a Node file system error with this code, such as ENOENT. */
+export declare function hasErrno(error: unknown, code: string): boolean;

package/dist/features/index.d.ts

@@ -0,0 +1,5 @@
+export { listLocalFeatures, loadFeature, parseFeature, type LoadedFeature, type LoadOptions, } from './load.js';
+export { fetchRemoteText, getHttps, readCappedText, registryUrl, type FetchLike, type FetchResponse, } from './remote.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

@@ -0,0 +1,30 @@
+import { type FeatureManifest } from '@mfeflow/contracts';
+import { type FsOps } from '../fs.js';
+import { type FetchLike } from './remote.js';
+import { type Trust } from './policy.js';
+export interface LoadedFeature {
+    manifest: FeatureManifest;
+    trust: Trust;
+    /** Reads a `from` file of a local feature. Absent for remote features. */
+    readAsset?: (relative: string) => Promise<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;
+export interface LoadOptions {
+    /** Folder holding one sub-folder per first-party or local feature. */
+    featuresDir?: string;
+    /** From mfeflow.json `registries`. */
+    registries?: Record<string, string>;
+    fetch?: FetchLike;
+    /** The version to ask a registry for, when its URL template has `{version}`. */
+    version?: string;
+    fs?: FsOps;
+}
+/**
+ * Finds a feature by name. `@ns/name` comes from that namespace's registry and
+ * is third-party; a plain name comes from the local `features/` folder and is
+ * trusted. Trust follows where the bytes came from, never what the manifest says.
+ */
+export declare function loadFeature(name: string, options: LoadOptions): Promise<LoadedFeature>;
+/** Names of the features in the local `features/` folder that have a feature.json. */
+export declare function listLocalFeatures(featuresDir: string, ops?: FsOps): Promise<string[]>;

package/dist/features/policy.d.ts

@@ -0,0 +1,27 @@
+import { type FeatureManifest, type TransformOp } from '@mfeflow/contracts';
+/** Where a feature came from decides what it may do. */
+export type Trust = 'first-party' | 'third-party';
+/** Fields a feature from a namespaced registry may have. Everything else is an E203. */
+export declare const THIRD_PARTY_KEYS: ReadonlySet<string>;
+export declare function isModuleSpecifier(value: string): boolean;
+/**
+ * True for a semver range or a dist-tag, the only things a registry resolves.
+ * Everything else (file:, link:, git, URLs, `npm:` aliases, `workspace:`,
+ * `catalog:`, paths) is refused because it is parsed by the package manager.
+ */
+export declare function isRegistryRange(range: string): boolean;
+/**
+ * Throws E203 unless `name` is a plain, namespaced script name that no package
+ * manager runs on its own. An allowlist on the shape, then the known hooks:
+ * lifecycle events, `pnpm:`/`npm:`/`yarn:`/`bun:` prefixes and every `pre` or
+ * `post` name, since what it wraps may be added to package.json later.
+ */
+export declare function assertPlainScript(name: string, label: string): void;
+/** Keys check: runs on the raw JSON, before the schema, so "hooks" is named rather than ignored. */
+export declare function assertAllowedKeys(value: Record<string, unknown>, label: string): void;
+/** Unknown op names are their own error, so authors learn what the built-ins are. */
+export declare function assertKnownOps(value: Record<string, unknown>, label: string): void;
+/** What a validated third-party manifest may not contain. */
+export declare function assertThirdPartyContent(manifest: FeatureManifest, label: string): void;
+/** What a third-party transform op may carry beyond the shape the schema already checks. */
+export declare function assertThirdPartyTransform(t: TransformOp, label: string): void;

package/dist/features/remote.d.ts

@@ -0,0 +1,34 @@
+/** The part of `Response` the loader uses, so tests can pass a plain object. */
+export interface FetchResponse {
+    ok: boolean;
+    status: number;
+    url?: string;
+    headers?: {
+        get(name: string): string | null;
+    };
+    /** When present the body is read from it, a chunk at a time, so the size cap holds. */
+    body?: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+    redirect?: 'follow' | 'manual';
+}) => Promise<FetchResponse>;
+/**
+ * The URL a namespaced feature lives at. `{name}` is the part after the slash and
+ * `{version}` the version asked for (`latest` when none), both URL-encoded.
+ */
+export declare function registryUrl(name: string, registries: Record<string, string>, version?: string): string;
+/**
+ * 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.
+ */
+export declare function getHttps(url: string, fetchImpl: FetchLike, code: 'E109' | 'E401'): 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>;
+/**
+ * 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
+ * cancelled instead of downloaded. `tooBig` builds the error to throw.
+ */
+export declare function readCappedText(response: FetchResponse, maxBytes: number, tooBig: () => Error): Promise<string>;

package/dist/features/resolve.d.ts

@@ -0,0 +1,20 @@
+import { type FeatureManifest } from '@mfeflow/contracts';
+import type { PlanBuilder } from '../plan.js';
+import type { MfeflowProject } from '../project.js';
+import type { LoadedFeature } from './load.js';
+export interface ResolveInput {
+    feature: LoadedFeature;
+    project: MfeflowProject;
+    builder: PlanBuilder;
+    /** Answers to the feature's prompts. Missing ones take the prompt's default. */
+    options?: Record<string, unknown>;
+    /** Features added in the same command, which count as installed for `requires` and `conflicts`. */
+    alsoAdding?: readonly string[];
+}
+/** Checks `value` against the prompts and fills in defaults. */
+export declare function resolveOptions(manifest: FeatureManifest, given?: Record<string, unknown>): Record<string, string | boolean>;
+/**
+ * Turns a loaded feature into edits on the plan builder: files, dependencies,
+ * scripts and transform ops. Nothing is written to disk and nothing is run.
+ */
+export declare function resolveFeature(input: ResolveInput): Promise<void>;

package/dist/features/schema-policy.d.ts

@@ -0,0 +1,15 @@
+import type { AddEnvKeyOp } from '@mfeflow/contracts';
+/**
+ * Validates the `schema` text of a third-party `add-env-key` and returns it
+ * re-emitted from the parsed tree. The text is pasted into the user's source
+ * and runs when the app starts, so only a call chain on `z`, `v` or `type`
+ * with literal arguments (and nested chains) is accepted, and the output is
+ * built from the tree, never from the input, so no comment or trailing text
+ * survives. With `form.string` (arktype's own syntax, `'string.url'`) a plain
+ * string literal is accepted too, re-emitted with its quotes escaped.
+ */
+export declare function sanitizeSchema(schema: string, label: string, form?: {
+    string?: boolean;
+}): string;
+/** `sanitizeSchema` for a single text or a per-validator map. */
+export declare function sanitizeSchemas(schema: AddEnvKeyOp['schema'], label: string): AddEnvKeyOp['schema'];

package/dist/features/write-policy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The form every path rule is checked on. macOS and Windows treat `.GIT`,
+ * `.git.` and a decomposed `é` as the same file as their plain spellings, so
+ * rules must never run on the raw text.
+ */
+export declare function policyKey(file: string): string;
+/** Files that change how the package manager or git hooks run code. Third-party features cannot write them. */
+export declare function isProtectedPath(file: string): boolean;
+/**
+ * Rules for every feature, first-party or not. Runs on the folded path, with
+ * rejection (never stripping) of anything a file system could read as a
+ * different name.
+ */
+export declare function assertWritable(file: string): void;
+/** True for a file a test runner or tool config loader would pick up by name or by folder. */
+export declare function isTestFilePath(file: string): boolean;
+/**
+ * Where a third-party feature may write: an allowlist, not a list of bad
+ * names. `relative` is the path inside the target; `joined` is the project
+ * path. Only plain ASCII names under `src/`, `public/` or `docs/` pass, so no
+ * dot folder, root file or package manager config can be named.
+ */
+export declare function assertThirdPartyPath(relative: string, joined: string): void;

package/dist/fs.d.ts

@@ -0,0 +1,24 @@
+/** The file system calls the engine makes, so tests can make one of them fail. */
+export interface FsOps {
+    readFile(file: string): Promise<string>;
+    writeFile(file: string, content: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    /** The path with every symlink resolved. Rejects with ENOENT when it does not exist. */
+    realpath(file: string): Promise<string>;
+    rm(file: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Returns the first directory it had to create, if any. */
+    mkdir(dir: string): Promise<string | undefined>;
+    /** Whether `file` is itself a symlink. False when it does not exist. */
+    isSymlink(file: string): Promise<boolean>;
+    /** Names of the sub-folders of `dir`. */
+    listDirs(dir: string): Promise<string[]>;
+}
+export declare const realFs: FsOps;
+/** File content, or undefined when the file does not exist. */
+export declare function readIfExists(ops: FsOps, file: string): Promise<string | undefined>;
+/** A sibling path for staging writes; same directory so the rename never crosses file systems. */
+export declare function tempSibling(file: string): string;
+/** Writes through a temp file and a rename, so readers never see half a file. */
+export declare function writeFileAtomic(ops: FsOps, file: string, content: string): Promise<void>;

package/dist/hash.d.ts

@@ -0,0 +1,4 @@
+/** Line endings differ between checkouts (autocrlf); the hash must not. */
+export declare function normalizeEol(content: string): string;
+/** `sha256-<hex>` of the content with LF line endings. */
+export declare function hashContent(content: string): string;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/** Name and version of this package. */
+export declare function packageInfo(): {
+    name: string;
+    version: string;
+};
+export { ERROR_CATALOGUE, hasErrno, isMfeflowError, messageOf, MfeflowError, type ErrorCode, type MfeflowErrorOptions, } from './errors.js';
+export { hashContent } from './hash.js';
+export { inOrder } from './sequence.js';
+export { realFs, type FsOps } from './fs.js';
+export { findDiverged, findProjectRoot, loadProject, parseProject, PROJECT_FILE, recordPlan, saveProject, serializeProject, type DivergedFile, type MfeflowProject, } from './project.js';
+export { emptyPlan, PlanBuilder, renderDiff, summarize, type ChangeAction, type DependencyAdd, type EnvKeyAdd, type FileChange, type Plan, type PlanBuilderOptions, type PlanFeature, type ReadFile, type ScriptAdd, } from './plan.js';
+export { applyPlan, type ApplyOptions, type ApplyResult, type InstallContext, type InstallStep, } from './apply.js';
+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 { fetchRemoteText, isProtectedPath, listLocalFeatures, loadFeature, parseFeature, getHttps, readCappedText, registryUrl, resolveFeature, resolveOptions, type FetchLike, type FetchResponse, type LoadedFeature, type LoadOptions, type ResolveInput, type Trust, } from './features/index.js';