mfeflow 0.3.0 → 0.4.0

package/README.md

@@ -13,20 +13,23 @@ pnpm dev                                    # shell on :4300, remotes on :4311,
 
 ## Commands
 
-| Command                               | Does                                                                                 |
-| ------------------------------------- | ------------------------------------------------------------------------------------ |
-| `mfeflow init [dir]`                  | New project: a shell, remotes (default `catalog`, `cart`), pnpm workspace, Turborepo |
-| `mfeflow add remote <name>`           | New remote with its registry entries and a route in every shell                      |
-| `mfeflow add shell <name>`            | New shell that routes to every existing remote                                       |
-| `mfeflow add <feature...>`            | Add features, or `@namespace/feature` from a registry in `mfeflow.json`              |
-| `mfeflow add env-key <KEY>`           | Add a typed env key: `--scope server` (env.ts) or `runtime`, with `--schema <expr>`  |
-| `mfeflow features [search]`           | List the features you can add                                                        |
-| `mfeflow dev`                         | Run the shell and every remote, one prefixed log each; follows `add remote`          |
-| `mfeflow doctor`                      | Singletons, compatibility, config health, drift; `--fix` repairs the safe ones       |
-| `mfeflow validate`                    | `mfeflow.json`, every `mfe.json` and every registry entry against their schemas      |
-| `mfeflow check-compat`                | Each remote's shared ranges against the shells it runs in                            |
-| `mfeflow budget`                      | Built first-load JS of the shell and each remote against the cost-model budget       |
-| `mfeflow --version`, `mfeflow --help` | Version, and help with examples (`mfeflow <command> --help` for one command)         |
+| Command                               | Does                                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------------------- |
+| `mfeflow init [dir]`                  | New project: a shell, remotes (default `catalog`, `cart`), pnpm workspace, Turborepo  |
+| `mfeflow add remote <name>`           | New remote with its registry entries and a route in every shell                       |
+| `mfeflow add shell <name>`            | New shell that routes to every existing remote                                        |
+| `mfeflow add <feature...>`            | Add features, or `@namespace/feature` from a registry you added with `registry add`   |
+| `mfeflow add env-key <KEY>`           | Add a typed env key: `--scope server` (env.ts) or `runtime`, with `--schema <expr>`   |
+| `mfeflow features [search]`           | List and search the features you can add, from mfeflow and every configured registry  |
+| `mfeflow registry add @ns <url>`      | Add a third-party feature registry (`https`, or `http` on loopback) to `mfeflow.json` |
+| `mfeflow registry list`, `remove @ns` | List the registries, or remove one                                                    |
+| `mfeflow registry build <dir>`        | Check a folder of features and write `index.json` and the files to host               |
+| `mfeflow dev`                         | Run the shell and every remote, one prefixed log each; follows `add remote`           |
+| `mfeflow doctor`                      | Singletons, compatibility, config health, drift; `--fix` repairs the safe ones        |
+| `mfeflow validate`                    | `mfeflow.json`, every `mfe.json` and every registry entry against their schemas       |
+| `mfeflow check-compat`                | Each remote's shared ranges against the shells it runs in                             |
+| `mfeflow budget`                      | Built first-load JS of the shell and each remote against the cost-model budget        |
+| `mfeflow --version`, `mfeflow --help` | Version, and help with examples (`mfeflow <command> --help` for one command)          |
 
 Features that ship with it: `core` and `tsconfig` (always), `lint-oxlint`, `url-factory`, `env-t3` and `testing`
 (default), `ci-github` and `git-hooks` (opt-in). `init` takes `--scope`, `--remotes a,b`, `--features a,b` and

package/dist/commands/features.d.ts

@@ -46,8 +46,8 @@ export declare const FEATURES_ARGS: {
     readonly search: {
         readonly type: 'positional';
         readonly required: false;
-        readonly description: 'Only features whose name or description contains this';
+        readonly description: 'Only features whose name, description or keywords contain this';
     };
 };
-export declare function matches(feature: FeatureInfo, search: string): boolean;
+export declare function matches(feature: FeatureInfo, search: string, keywords?: string[]): boolean;
 export declare function runFeatures(rt: Runtime, args: Record<string, unknown>, raw: readonly string[]): Promise<FeaturesResult>;

package/dist/commands/registry.d.ts

@@ -0,0 +1,52 @@
+import type { RegistryResult } from '../output.js';
+import type { Runtime } from '../runtime.js';
+export declare const REGISTRY_ARGS: {
+    readonly yes: {
+        readonly type: 'boolean';
+        readonly alias: 'y';
+        readonly description: 'Take the defaults and never prompt';
+    };
+    readonly preset: {
+        readonly type: 'string';
+        readonly description: 'Replay options from a JSON file or an https URL';
+        readonly valueHint: 'file|url';
+    };
+    readonly json: {
+        readonly type: 'boolean';
+        readonly description: 'Print one JSON document on stdout, nothing else';
+    };
+    readonly 'dry-run': {
+        readonly type: 'boolean';
+        readonly description: 'Print the summary and diff, write nothing';
+    };
+    readonly cwd: {
+        readonly type: 'string';
+        readonly description: 'Run as if started in this folder';
+        readonly valueHint: 'dir';
+    };
+    readonly install: {
+        readonly type: 'boolean';
+        readonly default: true;
+        readonly description: 'Run the package manager after writing (--no-install to skip)';
+    };
+    readonly verbose: {
+        readonly type: 'boolean';
+        readonly description: 'Show package manager output and stack traces';
+    };
+    readonly local: {
+        readonly type: 'string';
+        readonly description: 'Link @mfeflow/* from a built mfeflow checkout (env MFEFLOW_LOCAL)';
+        readonly valueHint: 'path';
+    };
+    readonly help: {
+        readonly type: 'boolean';
+        readonly alias: 'h';
+        readonly description: 'Show this help';
+    };
+    readonly out: {
+        readonly type: 'string';
+        readonly description: 'registry build: the folder to write (default: <dir>/dist)';
+        readonly valueHint: 'dir';
+    };
+};
+export declare function runRegistry(rt: Runtime, args: Record<string, unknown>, raw: readonly string[]): Promise<RegistryResult>;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { main } from './cli.js';
 export { COMMANDS } from './cli.js';
 export { EXIT, exitCodeFor } from './exit.js';
 export { validateResult } from './output.js';
-export type { AddResult, BudgetResult, DevResult, CliResult, FailureResult, FeatureInfo, FeaturesResult, InitResult, PlanReport, ReportResult, } from './output.js';
+export type { AddResult, BudgetResult, DevResult, CliResult, FailureResult, FeatureInfo, FeaturesResult, InitResult, PlanReport, RegistryEntryInfo, RegistryResult, RegistryStatus, ReportResult, } from './output.js';
 export { realRuntime, type Runtime } from './runtime.js';
 export type { Io } from './io.js';
 export type { Prompter } from './prompter.js';

package/dist/index.js

@@ -1,8 +1,8 @@
 import { stripVTControlCharacters } from "node:util";
-import { MfeflowError, PlanBuilder, applyPlan, dotenvKeys, findDiverged, findProjectRoot, getHttps, hasErrno, inOrder, isMfeflowError, loadFeature, loadProject, messageOf, parseFeature, readCappedText, realFs, recordPlan, renderDiff, renderTemplate, resolveFeature, runtimeConfigFiles, schemaKeys, serializeProject, summarize } from "@mfeflow/core";
+import { MfeflowError, PlanBuilder, applyPlan, buildRegistry, dotenvKeys, fetchFeatureIndex, findDiverged, findProjectRoot, getHttps, hasErrno, inOrder, isMfeflowError, loadFeature, loadProject, messageOf, parseFeature, readCappedText, realFs, recordPlan, renderDiff, renderTemplate, resolveFeature, runtimeConfigFiles, saveProject, schemaKeys, serializeProject, summarize, writeFileAtomic } from "@mfeflow/core";
 import { defineCommand, runCommand } from "citty";
 import node_path from "node:path";
-import { COST_MODEL, DOCS_URL, MFE_NAME, assetsFromManifest, isSafeRelativePath, judgeCost, round1, validateMfeManifest, validateRegistryEntry } from "@mfeflow/contracts";
+import { COST_MODEL, DOCS_URL, MFE_NAME, REGISTRY_NAMESPACE, assetsFromManifest, isSafeRelativePath, judgeCost, registryIndexUrl, registryTemplateProblem, round1, validateMfeManifest, validateRegistryEntry } from "@mfeflow/contracts";
 import promises from "node:fs/promises";
 import node_fs from "node:fs";
 import { createRequire } from "node:module";
@@ -765,6 +765,7 @@ function validateResult(value) {
             if (null !== value.search && 'string' != typeof value.search) c.add('search', 'must be text or null');
             c.objects(value, 'features', '', (f, p)=>{
                 for (const key of [
+                    'source',
                     'name',
                     'version',
                     "description"
@@ -775,6 +776,51 @@ function validateResult(value) {
                     'installed'
                 ])c.boolean(f, key, p);
             });
+            c.objects(value, 'registries', '', (r, p)=>{
+                for (const key of [
+                    'namespace',
+                    'index'
+                ])c.string(r, key, p);
+                if ('number' != typeof r.items) c.add(`${p}items`, 'must be a number');
+                if (null !== r.error) if (isObj(r.error)) for (const key of [
+                    'code',
+                    'message',
+                    'fix',
+                    'docs'
+                ])c.string(r.error, key, `${p}error.`);
+                else c.add(`${p}error`, 'must be an object or null');
+            });
+            break;
+        case 'registry':
+            if (![
+                'add',
+                'remove',
+                'list',
+                'build'
+            ].includes(String(value.action))) c.add('action', 'must be add, remove, list or build');
+            c.boolean(value, 'dryRun', '');
+            c.boolean(value, 'changed', '');
+            if (null !== value.root) c.string(value, 'root', '');
+            c.objects(value, 'registries', '', (r, p)=>{
+                for (const key of [
+                    'namespace',
+                    'url',
+                    'index'
+                ])c.string(r, key, p);
+            });
+            if (null !== value.build) if (isObj(value.build)) {
+                for (const key of [
+                    'namespace',
+                    'out'
+                ])c.string(value.build, key, 'build.');
+                c.texts(value.build, 'files', 'build.');
+                c.objects(value.build, 'features', 'build.', (f, p)=>{
+                    for (const key of [
+                        'name',
+                        'version'
+                    ])c.string(f, key, p);
+                });
+            } else c.add('build', 'must be an object or null');
             break;
         case 'doctor':
         case 'validate':
@@ -797,7 +843,7 @@ function validateResult(value) {
             if (!isObj(value.overrides)) c.add('overrides', 'must be an object');
             break;
         default:
-            c.add('command', 'must be init, add, features, doctor, validate, check-compat, budget or dev');
+            c.add('command', 'must be init, add, features, registry, doctor, validate, check-compat, budget or dev');
     }
     return c.issues;
 }
@@ -3483,60 +3529,121 @@ const FEATURES_ARGS = {
     search: {
         type: 'positional',
         required: false,
-        description: "Only features whose name or description contains this"
+        description: "Only features whose name, description or keywords contain this"
     },
     ...GLOBAL_ARGS
 };
-async function installedFeatures(cwd) {
+async function projectAt(cwd) {
     try {
-        const project = await loadProject(await findProjectRoot(cwd));
-        return new Set(Object.keys(project.features));
-    } catch  {
-        return new Set();
+        return await loadProject(await findProjectRoot(cwd));
+    } catch (error) {
+        if (isMfeflowError(error) && 'MFEFLOW_E102' === error.code) return;
+        throw error;
     }
 }
-function matches(feature, search) {
+function matches(feature, search, keywords = []) {
     const needle = search.toLowerCase();
-    return feature.name.toLowerCase().includes(needle) || feature.description.toLowerCase().includes(needle);
+    return feature.name.toLowerCase().includes(needle) || feature.description.toLowerCase().includes(needle) || keywords.some((keyword)=>keyword.toLowerCase().includes(needle));
 }
-function features_line(feature) {
+function features_line(feature, widths) {
     const tags = [
-        feature.always ? 'always' : feature.default ? 'default' : 'opt-in',
+        feature.always ? 'always' : 'mfeflow' === feature.source ? feature.default ? 'default' : 'opt-in' : 'registry',
         ...feature.installed ? [
             'installed'
         ] : []
     ];
-    return `  ${feature.name.padEnd(14)} ${feature.version.padEnd(7)} ${feature.description} [${tags.join(', ')}]`;
+    return `  ${feature.source.padEnd(widths.source)} ${feature.name.padEnd(widths.name)} ${feature.version.padEnd(7)} ${feature.description} [${tags.join(', ')}]`;
+}
+function fetchIndexes(rt, registries) {
+    return Promise.all(Object.entries(registries).toSorted(([a], [b])=>a.localeCompare(b)).map(async ([namespace, template])=>{
+        const base = {
+            namespace,
+            index: registryIndexUrl(template)
+        };
+        try {
+            const items = await fetchFeatureIndex(namespace, registries, rt.fetch);
+            return {
+                status: {
+                    ...base,
+                    items: items.length,
+                    error: null
+                },
+                items
+            };
+        } catch (error) {
+            const report = isMfeflowError(error) ? reportOf(error) : unexpectedReport(error);
+            return {
+                status: {
+                    ...base,
+                    items: 0,
+                    error: report
+                },
+                items: []
+            };
+        }
+    }));
 }
 async function runFeatures(rt, args, raw) {
     assertKnownFlags(raw, FEATURES_ARGS);
     const globals = readGlobals(args, rt.io.env, rt.io.cwd);
     const search = 'string' == typeof args.search && '' !== args.search ? args.search : null;
-    const installed = await installedFeatures(globals.cwd);
-    const all = await Promise.all(FIRST_PARTY.map(async (first)=>{
-        const { manifest } = await loadAny(first.name, {
-            roots: rt.roots
-        });
-        return {
-            name: first.name,
-            version: manifest.version,
-            description: manifest.description ?? '',
-            always: first.always,
-            default: first.default,
-            installed: installed.has(first.name)
-        };
-    }));
-    const features = null === search ? all : all.filter((f)=>matches(f, search));
+    const project = await projectAt(globals.cwd);
+    const installed = new Set(Object.keys(project?.features ?? {}));
+    const [firstParty, fetched] = await Promise.all([
+        Promise.all(FIRST_PARTY.map(async (first)=>{
+            const { manifest } = await loadAny(first.name, {
+                roots: rt.roots
+            });
+            return {
+                source: 'mfeflow',
+                name: first.name,
+                version: manifest.version,
+                description: manifest.description ?? '',
+                always: first.always,
+                default: first.default,
+                installed: installed.has(first.name)
+            };
+        })),
+        fetchIndexes(rt, project?.registries ?? {})
+    ]);
+    const fromRegistries = fetched.flatMap(({ status, items })=>items.toSorted((a, b)=>a.name.localeCompare(b.name)).map((item)=>{
+            const name = `${status.namespace}/${item.name}`;
+            return [
+                {
+                    source: status.namespace,
+                    name,
+                    version: item.version,
+                    description: item.description,
+                    always: false,
+                    default: false,
+                    installed: installed.has(name)
+                },
+                item.keywords ?? []
+            ];
+        }));
+    const features = [
+        ...firstParty.filter((f)=>null === search || matches(f, search)),
+        ...fromRegistries.filter(([f, keywords])=>null === search || matches(f, search, keywords)).map(([f])=>f)
+    ];
+    const registries = fetched.map((f)=>f.status);
     if (!globals.json) {
         if (0 === features.length) rt.io.stdout(`No features match "${search ?? ''}".`);
-        else rt.io.stdout(features.map(features_line).join('\n'));
-        rt.io.stdout('\nFrom a registry: mfeflow add @namespace/name (configure it under "registries" in mfeflow.json).');
+        else {
+            const widths = {
+                source: Math.max(...features.map((f)=>f.source.length)),
+                name: Math.max(14, ...features.map((f)=>f.name.length))
+            };
+            rt.io.stdout(features.map((f)=>features_line(f, widths)).join('\n'));
+        }
+        for (const { namespace, error } of registries)if (error) rt.io.stderr(`Could not read ${namespace}: ${error.message}\n  ${error.fix}`);
+        rt.io.stdout(0 === registries.length ? '\nFrom a registry: mfeflow registry add @namespace <url>, then mfeflow add @namespace/name.' : '\nAdd one with: mfeflow add @namespace/name.');
     }
     return {
         ok: true,
         command: 'features',
         search,
-        features
+        features,
+        registries
     };
 }
 const INIT_ARGS = {
@@ -3789,6 +3896,175 @@ function printInit(rt, result) {
     rt.io.stdout(`\nCreated ${result.root} with a shell and ${String(remotes.length)} remote${1 === remotes.length ? '' : 's'} (${remotes.join(', ')}).`);
     rt.io.stdout(`Next:\n${result.next.map((line)=>`  ${line}`).join('\n')}`);
 }
+const REGISTRY_ARGS = {
+    out: {
+        type: 'string',
+        description: 'registry build: the folder to write (default: <dir>/dist)',
+        valueHint: 'dir'
+    },
+    ...GLOBAL_ARGS
+};
+const USAGE = 'mfeflow registry add @namespace <url-template> | list | remove @namespace | build <dir>';
+function registry_entries(project) {
+    return Object.entries(project.registries ?? {}).toSorted(([a], [b])=>a.localeCompare(b)).map(([namespace, url])=>({
+            namespace,
+            url,
+            index: registryIndexUrl(url)
+        }));
+}
+function registry_result(action, globals, extra) {
+    return {
+        ok: true,
+        command: 'registry',
+        action,
+        dryRun: globals.dryRun,
+        root: null,
+        changed: false,
+        build: null,
+        ...extra
+    };
+}
+function assertNamespace(namespace, verb) {
+    if (void 0 === namespace) throw new MfeflowError('E107', `registry ${verb} needs a namespace like @someone`);
+    if ('@mfeflow' === namespace) throw new MfeflowError('E107', '@mfeflow is reserved for the features that ship with mfeflow');
+    if (!REGISTRY_NAMESPACE.test(namespace)) throw new MfeflowError('E107', `"${namespace}" is not a namespace; they start with @ and use lower-case letters, digits and "-" (for example @someone)`);
+    return namespace;
+}
+async function projectOf(globals) {
+    const root = await findProjectRoot(globals.cwd);
+    return {
+        root,
+        project: await loadProject(root)
+    };
+}
+async function save(globals, root, project, registries) {
+    const { registries: _old, ...rest } = project;
+    const next = Object.keys(registries).length > 0 ? {
+        ...rest,
+        registries
+    } : rest;
+    if (!globals.dryRun) await saveProject(root, next);
+    return next;
+}
+async function addRegistry(rt, globals, namespaceArg, url) {
+    const namespace = assertNamespace(namespaceArg, 'add');
+    if (void 0 === url) throw new MfeflowError('E107', `registry add needs a URL: mfeflow registry add ${namespace} https://example.com/{name}.json`);
+    const problem = registryTemplateProblem(url);
+    if (void 0 !== problem) throw new MfeflowError('E107', `the URL ${problem}`);
+    const { root, project } = await projectOf(globals);
+    const current = project.registries ?? {};
+    const existing = current[namespace];
+    if (existing === url) {
+        if (!globals.json) rt.io.stdout(`${namespace} already points at ${url}; nothing to do.`);
+        return registry_result('add', globals, {
+            root,
+            registries: registry_entries(project)
+        });
+    }
+    if (void 0 !== existing) throw new MfeflowError('E107', `${namespace} already points at ${existing}`, {
+        fix: `Run \`mfeflow registry remove ${namespace}\` first, then add it again.`
+    });
+    const next = await save(globals, root, project, {
+        ...current,
+        [namespace]: url
+    });
+    if (!globals.json) rt.io.stdout(globals.dryRun ? `Dry run: would add ${namespace} -> ${url}. Nothing was written.` : `Added ${namespace} -> ${url}\nSee what it offers: mfeflow features`);
+    return registry_result('add', globals, {
+        root,
+        changed: true,
+        registries: registry_entries(next)
+    });
+}
+async function removeRegistry(rt, globals, namespaceArg) {
+    const namespace = assertNamespace(namespaceArg, 'remove');
+    const { root, project } = await projectOf(globals);
+    const { [namespace]: url, ...rest } = project.registries ?? {};
+    if (void 0 === url) throw new MfeflowError('E107', `${namespace} is not in this project's registries`, {
+        fix: 'List them with `mfeflow registry list`.'
+    });
+    const using = Object.keys(project.features).filter((name)=>name.startsWith(`${namespace}/`));
+    if (using.length > 0) throw new MfeflowError('E107', `${using.join(', ')} installed from ${namespace}`, {
+        fix: `Keep ${namespace} while they are installed: \`mfeflow add remote\` and \`add shell\` fetch them again and fail without it.`
+    });
+    const next = await save(globals, root, project, rest);
+    if (!globals.json) rt.io.stdout(globals.dryRun ? `Dry run: would remove ${namespace}. Nothing was written.` : `Removed ${namespace} (${url}).`);
+    return registry_result('remove', globals, {
+        root,
+        changed: true,
+        registries: registry_entries(next)
+    });
+}
+async function listRegistries(rt, globals) {
+    const { root, project } = await projectOf(globals);
+    const registries = registry_entries(project);
+    if (!globals.json) if (0 === registries.length) rt.io.stdout('No registries. Add one: mfeflow registry add @namespace https://example.com/{name}.json');
+    else {
+        const width = Math.max(...registries.map((r)=>r.namespace.length));
+        rt.io.stdout(registries.map((r)=>`  ${r.namespace.padEnd(width)}  ${r.url}`).join('\n'));
+    }
+    return registry_result('list', globals, {
+        root,
+        registries
+    });
+}
+async function buildFolder(rt, globals, args, dirArg) {
+    if (void 0 === dirArg) throw new MfeflowError('E107', 'registry build needs the folder that holds your features: mfeflow registry build ./my-registry');
+    const dir = node_path.resolve(globals.cwd, dirArg);
+    const out = node_path.resolve(globals.cwd, args_text(args, 'out') ?? node_path.join(dirArg, 'dist'));
+    const built = await buildRegistry(dir);
+    if (!globals.dryRun) await inOrder(built.files, (file)=>writeFileAtomic(realFs, node_path.join(out, ...file.path.split('/')), file.content));
+    if (!globals.json) {
+        const lines = built.features.map((f)=>`  ${f.name} ${f.version}`);
+        rt.io.stdout([
+            `${globals.dryRun ? 'Dry run: would build' : 'Built'} ${String(built.features.length)} feature(s) for ${built.namespace}:`,
+            ...lines,
+            '',
+            `${globals.dryRun ? 'Would write' : 'Wrote'} ${String(built.files.length)} files to ${out}`,
+            '',
+            "Host that folder on any static host (GitHub Pages works). Users then run:",
+            `  mfeflow registry add ${built.namespace} https://<your-host>/{name}.json`
+        ].join('\n'));
+    }
+    return registry_result('build', globals, {
+        registries: [],
+        build: {
+            namespace: built.namespace,
+            out,
+            features: built.features.map(({ name, version })=>({
+                    name,
+                    version
+                })),
+            files: built.files.map((f)=>f.path)
+        }
+    });
+}
+async function runRegistry(rt, args, raw) {
+    assertKnownFlags(raw, REGISTRY_ARGS);
+    const globals = readGlobals(args, rt.io.env, rt.io.cwd);
+    const positional = Array.isArray(args._) ? args._.map(String) : [];
+    const [action, first, second] = positional;
+    const takes = {
+        add: 2,
+        remove: 1,
+        list: 0,
+        build: 1
+    };
+    const surplus = positional[(takes[action ?? ''] ?? 1 / 0) + 1];
+    if (void 0 !== surplus) throw new MfeflowError('E107', `unexpected "${surplus}" (${USAGE})`);
+    switch(action){
+        case 'add':
+            return addRegistry(rt, globals, first, second);
+        case 'remove':
+            return removeRegistry(rt, globals, first);
+        case 'list':
+            return listRegistries(rt, globals);
+        case 'build':
+            return buildFolder(rt, globals, args, first);
+        case void 0:
+        default:
+            throw new MfeflowError('E107', void 0 === action ? `registry needs an action (${USAGE})` : `unknown action "${action}" (${USAGE})`);
+    }
+}
 const REPO_URL = 'https://github.com/mfeflow/mfeflow';
 function flagLabel(name, def) {
     const alias = 'alias' in def ? [
@@ -4062,7 +4338,7 @@ const COMMANDS = [
     },
     {
         name: 'features',
-        summary: 'list the features you can add',
+        summary: 'list and search the features you can add, from mfeflow and your registries',
         usage: 'mfeflow features [search] [options]',
         args: FEATURES_ARGS,
         examples: [
@@ -4072,6 +4348,20 @@ const COMMANDS = [
         ],
         run: runFeatures
     },
+    {
+        name: 'registry',
+        summary: 'configure third-party feature registries, or build one to host',
+        usage: 'mfeflow registry add @namespace <url-template> | mfeflow registry list | mfeflow registry remove @namespace | mfeflow registry build <dir> [--out dir]',
+        args: REGISTRY_ARGS,
+        examples: [
+            'mfeflow registry add @acme https://acme.github.io/features/{name}.json',
+            'mfeflow registry add @test http://127.0.0.1:4010/{name}.json   # plain http: loopback hosts only',
+            'mfeflow registry list --json',
+            'mfeflow registry remove @acme --dry-run',
+            'mfeflow registry build ./my-registry --out ./site'
+        ],
+        run: runRegistry
+    },
     {
         name: 'doctor',
         summary: 'check singletons, compatibility, config and drift; --fix repairs the safe ones',

package/dist/output.d.ts

@@ -57,6 +57,9 @@ export interface AddResult extends WriteReport {
     skipped: string[];
 }
 export interface FeatureInfo {
+    /** `mfeflow` for the features that ship with the CLI, otherwise the registry's namespace, like `@test`. */
+    source: string;
+    /** What you pass to `mfeflow add`: `lint-oxlint`, or `@test/hello` for a registry's. */
     name: string;
     version: string;
     description: string;
@@ -64,11 +67,50 @@ export interface FeatureInfo {
     default: boolean;
     installed: boolean;
 }
+export interface RegistryStatus {
+    namespace: string;
+    /** The index.json asked for. */
+    index: string;
+    /** How many items it lists. */
+    items: number;
+    /** Why it could not be read; the other registries are listed regardless. */
+    error: ErrorReport | null;
+}
 export interface FeaturesResult {
     ok: true;
     command: 'features';
     search: string | null;
     features: FeatureInfo[];
+    registries: RegistryStatus[];
+}
+export interface RegistryEntryInfo {
+    namespace: string;
+    /** The URL template from mfeflow.json. */
+    url: string;
+    /** Where its index.json is. */
+    index: string;
+}
+export interface RegistryResult {
+    ok: true;
+    command: 'registry';
+    action: 'add' | 'remove' | 'list' | 'build';
+    dryRun: boolean;
+    /** The project folder; null for `build`, which needs none. */
+    root: string | null;
+    /** Whether mfeflow.json changed (or would have, for a dry run). */
+    changed: boolean;
+    /** The registries of the project after the action. */
+    registries: RegistryEntryInfo[];
+    build: {
+        namespace: string;
+        out: string;
+        features: {
+            name: string;
+            version: string;
+        }[];
+        /** Relative to `out`. */
+        files: string[];
+    } | null;
 }
 /** What `doctor`, `validate` and `check-compat` print with `--json`. `ok` is false when any finding is an error. */
 export interface ReportResult {
@@ -147,7 +189,7 @@ export interface FailureResult {
     error: ErrorReport;
     exitCode: number;
 }
-export type CliResult = InitResult | AddResult | FeaturesResult | ReportResult | BudgetResult | DevResult | FailureResult;
+export type CliResult = InitResult | AddResult | FeaturesResult | RegistryResult | ReportResult | BudgetResult | DevResult | 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/package.json

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