mfeflow 0.4.0 → 0.5.0

package/dist/output.d.ts

@@ -1,4 +1,4 @@
-import type { Issue } from '@mfeflow/contracts';
+import type { Issue, RegistryIndex } from '@mfeflow/contracts';
 import { type Plan } from '@mfeflow/core';
 import { type ErrorReport } from './exit.js';
 import type { Finding } from './findings.js';
@@ -12,11 +12,13 @@ export interface PlanReport {
         path: string;
         action: 'create' | 'patch' | 'delete';
     }[];
+    /** `thirdParty` (only present when true): a feature from a registry asked for it. */
     dependencies: {
         file: string;
         name: string;
         range: string;
         dev: boolean;
+        thirdParty?: boolean;
     }[];
     scripts: {
         file: string;
@@ -69,8 +71,10 @@ export interface FeatureInfo {
 }
 export interface RegistryStatus {
     namespace: string;
-    /** The index.json asked for. */
+    /** The index.json asked for, with token-like query values hidden. */
     index: string;
+    /** False: the user has not trusted this registry yet, so nothing was requested from it. */
+    trusted: boolean;
     /** How many items it lists. */
     items: number;
     /** Why it could not be read; the other registries are listed regardless. */
@@ -85,15 +89,17 @@ export interface FeaturesResult {
 }
 export interface RegistryEntryInfo {
     namespace: string;
-    /** The URL template from mfeflow.json. */
+    /** The URL template from mfeflow.json, with token-like query values hidden. */
     url: string;
     /** Where its index.json is. */
     index: string;
+    /** Whether the user has trusted this namespace at this URL. */
+    trusted: boolean;
 }
 export interface RegistryResult {
     ok: true;
     command: 'registry';
-    action: 'add' | 'remove' | 'list' | 'build';
+    action: 'add' | 'remove' | 'list' | 'build' | 'trust' | 'untrust';
     dryRun: boolean;
     /** The project folder; null for `build`, which needs none. */
     root: string | null;
@@ -184,12 +190,78 @@ export interface DevResult {
     /** Stopped with Ctrl+C or a termination signal. */
     interrupted: boolean;
 }
+export interface PlannedUpload {
+    key: string;
+    bytes: number;
+    contentType: string;
+    cacheControl: string;
+    /** `create-only`: refuses to overwrite. `if-match`: only if the index is the one that was read. */
+    guard: 'create-only' | 'if-match' | 'none';
+}
+/** What `deploy`, `promote` and `rollback` print with `--json`. `ok` is false when a gate failed. */
+export interface DeployResult {
+    ok: boolean;
+    command: 'deploy' | 'promote' | 'rollback';
+    dryRun: boolean;
+    root: string;
+    env: string;
+    /** The env a promote copied from; null otherwise. */
+    fromEnv: string | null;
+    /** The host as a person wrote it, never an endpoint or a credential. */
+    host: string;
+    remote: string;
+    version: string;
+    /** The version the env served before; null when the remote was not deployed there. */
+    servedBefore: string | null;
+    /** The index now points at `version` (false for a dry run, `--no-publish`, a failed gate, or when it already did). */
+    published: boolean;
+    previous: string | null;
+    rolledBackFrom: string | null;
+    /** Everything the run uploads, in order, the index last. */
+    uploads: PlannedUpload[];
+    uploaded: string[];
+    skipped: string[];
+    /** The registry/envs file written to match the host; null when none was. */
+    localEntry: string | null;
+    /** The index the run would write. Only for a dry run. */
+    index?: RegistryIndex;
+    warnings: string[];
+    findings: Finding[];
+}
+export interface StatusRemote {
+    name: string;
+    version: string;
+    previous: string | null;
+    history: string[];
+    rolledBackFrom: string | null;
+    /** The version in `registry/envs/<env>/<name>.json`; null when there is no such file. */
+    local: string | null;
+    /** Versions on the host newer than `version` that no environment points at; null when the host cannot list. */
+    unreferenced: string[] | null;
+    drift: string[];
+}
+export interface StatusEnv {
+    env: string;
+    /** The host has an index for this env. */
+    published: boolean;
+    /** When that index was written. The index records no per-remote time. */
+    generatedAt: string | null;
+    remotes: StatusRemote[];
+}
+export interface StatusResult {
+    ok: boolean;
+    command: 'status';
+    root: string;
+    host: string;
+    envs: StatusEnv[];
+    findings: Finding[];
+}
 export interface FailureResult {
     ok: false;
     error: ErrorReport;
     exitCode: number;
 }
-export type CliResult = InitResult | AddResult | FeaturesResult | RegistryResult | ReportResult | BudgetResult | DevResult | FailureResult;
+export type CliResult = InitResult | AddResult | FeaturesResult | RegistryResult | ReportResult | BudgetResult | DevResult | DeployResult | StatusResult | FailureResult;
 /** The plan as plain data for `--json`, without file contents. Features are listed once. */
 export declare function planReport(plan: Plan): PlanReport;
 /** Checks a document the CLI printed with `--json`. Returns the problems; empty means valid. */

package/dist/pipeline.d.ts

@@ -5,3 +5,11 @@ export declare function projectReader(root: string): (file: string) => Promise<s
 export declare function createBuilder(root: string, checkout: string | undefined): PlanBuilder;
 /** `plan` with the `mfeflow.json` change added, for the summary and the diff. */
 export declare function withProjectChange(plan: Plan, project: MfeflowProject): Plan;
+/**
+ * `project` with `cli` set to the running version, but only when the plan already changes
+ * something and only upward: an older CLI never lowers it, and a run with nothing to do
+ * leaves `mfeflow.json` alone.
+ */
+export declare function stampCli(project: MfeflowProject, plan: Plan): MfeflowProject;
+/** `project` with `cli` raised to the running version; never lowered. */
+export declare function raiseCli(project: MfeflowProject): MfeflowProject;

package/dist/publish.d.ts

@@ -0,0 +1,89 @@
+import type { MfeManifest, RegistryEntry, RegistryIndex, RegistryIndexRemote } from '@mfeflow/contracts';
+import { type ErrorCode } from '@mfeflow/core';
+import { type ApplyResult, type DeployPlan, type GateCode, type RegistryHost } from '@mfeflow/registry/static';
+import { type Globals } from './args.js';
+import { type Finding } from './findings.js';
+import { type AppView, type ProjectView } from './inspect.js';
+import type { PlannedUpload } from './output.js';
+import type { Runtime } from './runtime.js';
+export declare const GATE_CODES: Record<GateCode, ErrorCode>;
+export interface Session {
+    rt: Runtime;
+    globals: Globals;
+    view: ProjectView;
+    host: RegistryHost;
+    hostLabel: string;
+    /** Secret values to scrub from anything printed. */
+    secrets: string[];
+    /** `--base-url`, else `registry.baseUrl` from mfeflow.json. */
+    baseUrl: string | undefined;
+}
+export declare function envOf(args: Record<string, unknown>, key?: string): string;
+export declare function positionals(args: Record<string, unknown>, max: number, usage: string): string[];
+export declare function openSession(rt: Runtime, args: Record<string, unknown>, raw?: Globals): Promise<Session>;
+/**
+ * A base URL ends up in a public index, so it must be an https URL (http only on localhost) with no
+ * credentials, query or fragment. Returns the normalised form without a trailing slash.
+ */
+export declare function normalizeBaseUrl(value: string, label: string): string;
+/** A failure from the host or the files around it as the catalogue error that names it. Secrets never reach the message. */
+export declare function hostFailure(error: unknown, secrets: readonly string[]): Error;
+/** Runs host work, turning host errors into catalogue errors. */
+export declare function onHost<T>(s: Session, work: () => Promise<T>): Promise<T>;
+export declare function remoteApp(view: ProjectView, name: string | undefined): AppView & {
+    mfe: MfeOk;
+};
+type MfeOk = {
+    state: 'ok';
+    value: MfeManifest;
+};
+/** The versions the shell has, for the packages a remote's compatibility is judged on. */
+export declare function shellVersions(view: ProjectView, mfe: MfeManifest): Promise<Record<string, string>>;
+export declare const shellManifestKey: (env: string) => string;
+/** The shell's deployed `mf-manifest.json`: the file given, else the one on the host under the env. */
+export declare function readShellManifest(s: Session, env: string, file: string | undefined): Promise<{
+    manifest?: unknown;
+    warnings: string[];
+}>;
+/** Environments that have an index on the host. Empty when the host cannot list. */
+export declare function hostEnvs(s: Session): Promise<string[]>;
+export declare function currentIndex(s: Session, env: string): Promise<{
+    index: RegistryIndex | undefined;
+    etag?: string;
+}>;
+/** Where artifacts are served from: the setting, else read back from an entry already in the index. */
+export declare function baseUrlFor(s: Session, index: RegistryIndex | undefined): string;
+export declare function describeUploads(plan: DeployPlan): PlannedUpload[];
+export declare function gateFindings(plan: DeployPlan, app: string): Finding[];
+export interface Planned {
+    plan: DeployPlan;
+    /** The remote's entry in the index before this run. */
+    before: RegistryIndexRemote | undefined;
+    warnings: string[];
+    /** The pointer already is where the command would move it. */
+    noop?: boolean;
+}
+export interface Committed {
+    planned: Planned;
+    applied: ApplyResult | undefined;
+    /** The index was written. */
+    published: boolean;
+}
+export interface CommitOptions {
+    env: string;
+    name: string;
+    dryRun: boolean;
+    /** Upload the artifacts and leave the index where it is. */
+    noPublish?: boolean;
+    /** Reads the host and plans. Runs again after another writer got in first. */
+    plan: () => Promise<Planned>;
+}
+/**
+ * Plans and applies. When another writer moves the index between the read and the write, reads it
+ * again, plans again and tries once more; a second collision stops with E510 naming what changed.
+ */
+export declare function commit(s: Session, options: CommitOptions): Promise<Committed>;
+/** The entry `registry/envs/<env>/<name>.json` records for what the index serves. */
+export declare function localEntryOf(remote: RegistryIndexRemote): RegistryEntry;
+export declare function writeLocalEntry(root: string, env: string, remote: RegistryIndexRemote): Promise<string>;
+export {};

package/dist/runtime.d.ts

@@ -1,8 +1,9 @@
-import type { FetchLike } from '@mfeflow/core';
+import { type FetchLike } from '@mfeflow/core';
 import { type AssetRoots } from './assets.js';
 import { type Io } from './io.js';
 import { type DevHost } from './proc.js';
 import { type Prompter } from './prompter.js';
+import type { RegistryHost } from '@mfeflow/registry/static';
 import { type System } from './system.js';
 /** Everything a command touches outside its own arguments. Tests replace the parts they watch. */
 export interface Runtime {
@@ -11,7 +12,13 @@ export interface Runtime {
     system: System;
     fetch: FetchLike;
     roots: AssetRoots;
+    /** Where per-user settings live, like the registries the user trusts. */
+    configDir: string;
     /** Processes, signals and file watching for `mfeflow dev`. Defaults to the real ones. */
     dev?: DevHost;
+    /** `fetch` for S3 hosts. Tests stand in for the network. */
+    hostFetch?: typeof fetch;
+    /** Wraps the registry host `deploy`, `promote`, `rollback` and `status` open. Tests inject a second writer. */
+    wrapHost?: (host: RegistryHost) => RegistryHost;
 }
 export declare function realRuntime(io?: Io): Runtime;

package/dist/testing.d.ts

@@ -0,0 +1,66 @@
+import { type MfeflowError } from '@mfeflow/core';
+import type { Io } from './io.js';
+import type { DevHost, DevProcess, DevSpec, WaitPolicy } from './proc.js';
+import type { Prompter } from './prompter.js';
+import type { Runtime } from './runtime.js';
+import type { System } from './system.js';
+/** The checkout this package lives in; `--local` tests point at it. */
+export declare const REPO: string;
+export interface Recorded {
+    out: string[];
+    err: string[];
+}
+export declare function fakeIo(overrides?: Partial<Io>): Io & Recorded;
+/** Answers prompts in the order they are asked, from `answers`; records the messages. */
+export declare function scriptedPrompter(answers?: readonly unknown[]): Prompter & {
+    asked: string[];
+};
+export interface SystemCalls {
+    installs: {
+        root: string;
+        packageManager: string;
+        verbose: boolean;
+    }[];
+    gitInits: string[];
+}
+export declare function fakeSystem(options?: {
+    installError?: Error;
+    gitInit?: boolean;
+}): System & SystemCalls;
+export interface FakeProc extends DevProcess {
+    spec: DevSpec;
+    stopped: boolean;
+    /** What the process prints. */
+    print(text: string): void;
+    /** The process ends by itself. */
+    exit(code: number | null): void;
+}
+export interface FakeDev extends DevHost {
+    procs: FakeProc[];
+    /** Ports `portFree` reports as taken. */
+    busy: Set<number>;
+    watched: string[][];
+    /** The watched files changed. */
+    change(): void;
+    /** Ctrl+C. */
+    interrupt(): void;
+    waitPolicy: WaitPolicy;
+}
+export declare function fakeDev(): FakeDev;
+export type TestRuntime = Runtime & {
+    io: Io & Recorded;
+    system: System & SystemCalls;
+    dev: FakeDev;
+};
+export declare function testRuntime(overrides?: Partial<Pick<Runtime, 'prompter' | 'fetch' | 'roots' | 'configDir'>> & {
+    /** Namespaces trusted for this run, through MFEFLOW_TRUST_REGISTRIES. */
+    trust?: string[];
+}): TestRuntime;
+export declare function tempDir(prefix?: string): Promise<string>;
+export declare function removeDir(dir: string): Promise<void>;
+/** Every file under `dir`, as `/`-separated paths mapped to content. */
+export declare function readTree(dir: string): Promise<Record<string, string>>;
+/** Awaits a promise that must reject with an MfeflowError and returns it. */
+export declare function failure(promise: Promise<unknown>): Promise<MfeflowError>;
+/** Calls `fn`, which must throw an MfeflowError, and returns it. */
+export declare function thrown(fn: () => unknown): MfeflowError;

package/dist/trust.d.ts

@@ -0,0 +1,4 @@
+import { type Trusted } from '@mfeflow/core';
+import type { Runtime } from './runtime.js';
+/** What this user trusts among `registries`: the trust file, or MFEFLOW_TRUST_REGISTRIES (public hosts only unless pinned to a template). */
+export declare function trustedIn(rt: Runtime, registries: Record<string, string> | undefined): Promise<Trusted>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mfeflow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Create and grow a React micro-frontend platform: mfeflow init, add remote, add <feature>.",
   "keywords": [
     "micro-frontend",
@@ -49,14 +49,15 @@
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",
-    "@mfeflow/contracts": "0.4.0",
-    "@mfeflow/core": "0.4.0",
+    "@mfeflow/contracts": "0.5.0",
+    "@mfeflow/core": "0.5.0",
+    "@mfeflow/registry": "0.5.0",
     "citty": "0.2.2",
     "semver": "7.8.5",
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@mfeflow/rsbuild": "0.4.0",
+    "@mfeflow/rsbuild": "0.5.0",
     "@rslib/core": "1.0.5",
     "@types/node": "26.6.6",
     "@types/semver": "7.8.0",