@mfeflow/contracts 0.2.0 → 0.4.0

package/dist/docs.d.ts

@@ -7,6 +7,7 @@ export declare const SCHEMA_URLS: {
     readonly feature: "https://mfeflow.github.io/mfeflow/schema/feature.json";
     readonly registryEntry: "https://mfeflow.github.io/mfeflow/schema/registry-entry.json";
     readonly registryIndex: "https://mfeflow.github.io/mfeflow/schema/registry-index.json";
+    readonly featureRegistryIndex: "https://mfeflow.github.io/mfeflow/schema/feature-registry-index.json";
 };
 export type SchemaName = keyof typeof SCHEMA_URLS;
 /** The docs page for an error code such as `E102`. */

package/dist/feature-registry.d.ts

@@ -0,0 +1,31 @@
+import { type Issue } from './validate.js';
+/** One feature a third-party registry offers. `name` has no namespace: the registry's own namespace goes in front. */
+export interface FeatureRegistryItem {
+    name: string;
+    version: string;
+    description: string;
+    keywords?: string[];
+}
+/** `<base>/index.json` of a third-party feature registry. */
+export interface FeatureRegistryIndex {
+    $schema?: string;
+    items: FeatureRegistryItem[];
+}
+export declare const REGISTRY_ITEM_NAME: RegExp;
+export declare const MAX_INDEX_ITEMS = 1000;
+export declare const MAX_DESCRIPTION = 300;
+export declare const MAX_KEYWORDS = 20;
+export declare const MAX_KEYWORD = 40;
+/** Plain http is allowed for the machine you are on, so a registry can be tried before it is hosted. */
+export declare function isLoopbackHttp(url: URL): boolean;
+/** True when `url` is https, or http on a loopback host. */
+export declare function isRegistryProtocol(url: URL): boolean;
+/** Why `template` cannot be a registry URL, or undefined when it can. */
+export declare function registryTemplateProblem(template: string): string | undefined;
+/**
+ * Where a registry's `index.json` is: in the folder the template starts in, before the first
+ * segment that has a placeholder. `https://x.dev/r/{name}.json` has its index at `https://x.dev/r/index.json`.
+ */
+export declare function registryIndexUrl(template: string): string;
+export declare function validateFeatureRegistryIndex(value: unknown): Issue[];
+export declare function isFeatureRegistryIndex(value: unknown): value is FeatureRegistryIndex;

package/dist/feature.d.ts

@@ -159,6 +159,8 @@ export interface FeatureManifest {
     name: string;
     version: string;
     description?: string;
+    /** Words a registry's `index.json` lists for search. */
+    keywords?: string[];
     prompts?: FeaturePrompt[];
     requires?: string[];
     conflicts?: string[];

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { ANALYTICS_EVENT, EVENT_NAME, EXPOSE, isMfeManifest, MFE_NAME, ROUTE, va
 export { assetsFromManifest, type RemoteAssets } from './manifest-assets.js';
 export { injectIntoHead, registryInjection, type InjectionOptions, type RouteNeed, } from './html-injection.js';
 export { isRegistryEntry, isRegistryIndex, validateRegistryEntry, validateRegistryIndex, type RegistryEntry, type RegistryIndex, type RegistryIndexRemote, } from './registry.js';
-export { FILE_HASH, isMfeflowProject, validateMfeflowProject, type MfeflowProject, type ProjectBudget, } from './project.js';
+export { isFeatureRegistryIndex, isLoopbackHttp, isRegistryProtocol, registryIndexUrl, registryTemplateProblem, validateFeatureRegistryIndex, MAX_DESCRIPTION, MAX_INDEX_ITEMS, REGISTRY_ITEM_NAME, type FeatureRegistryIndex, type FeatureRegistryItem, } from './feature-registry.js';
+export { FILE_HASH, REGISTRY_NAMESPACE, isMfeflowProject, validateMfeflowProject, type MfeflowProject, type ProjectBudget, } from './project.js';
 export { COST_MODEL, judgeCost, round1, splitScripts, type CostLine, type CostModel, type CostSample, type CostVerdict, } from './cost-model.js';
 export { FEATURE_CONDITION, FEATURE_NAME, isFeatureManifest, TRANSFORM_OPS, validateFeatureManifest, type AddBootStepOp, type AddEnvKeyOp, type AddImportOp, type AddRouteOp, type AddSharedOp, type AddWorkflowStepOp, type EnvValidator, type FeatureCondition, type FeatureDependency, type FeatureFile, type FeatureManifest, type FeatureMigration, type FeaturePrompt, type FeatureScript, type FeatureTarget, type Literal, type PromptValue, type TransformOp, type TransformOpName, type WorkflowStep, type WrapProviderOp, } from './feature.js';
 export { DOCS_URL, SCHEMA_URLS, errorDocsUrl, type SchemaName } from './docs.js';

package/dist/index.js

@@ -435,6 +435,99 @@ function isRegistryEntry(value) {
 function isRegistryIndex(value) {
     return 0 === validateRegistryIndex(value).length;
 }
+const INDEX_VERSION = /^\d{1,9}\.\d{1,9}\.\d{1,9}(?:-[0-9A-Za-z.-]{1,64})?(?:\+[0-9A-Za-z.-]{1,64})?$/;
+const REGISTRY_ITEM_NAME = /^[a-z][a-z0-9-]*$/;
+const MAX_INDEX_ITEMS = 1000;
+const MAX_DESCRIPTION = 300;
+const MAX_KEYWORDS = 20;
+const MAX_KEYWORD = 40;
+const INVISIBLE = /[\p{Cc}\p{Cf}\p{Cn}\p{Co}\p{Cs}]/u;
+const LOOPBACK_HOSTS = new Set([
+    '127.0.0.1',
+    'localhost',
+    '[::1]'
+]);
+function isLoopbackHttp(url) {
+    return 'http:' === url.protocol && LOOPBACK_HOSTS.has(url.hostname);
+}
+function isRegistryProtocol(url) {
+    return 'https:' === url.protocol || isLoopbackHttp(url);
+}
+const PLACEHOLDER = /\{([^{}]*)\}/g;
+function registryTemplateProblem(template) {
+    if (!template.includes('{name}')) return 'must contain {name}';
+    const unknown = [
+        ...template.matchAll(PLACEHOLDER)
+    ].map((m)=>m[1] ?? '').find((name)=>'name' !== name && 'version' !== name);
+    if (void 0 !== unknown) return `has {${unknown}}; only {name} and {version} are placeholders`;
+    if (/[{}]/.test(template.replaceAll(PLACEHOLDER, ''))) return 'has an unmatched { or }';
+    const origin = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i.exec(template);
+    if (origin?.[1]?.includes('{') === true) return 'has a placeholder in the host; put it in the path';
+    const first = template.search(/\{(?:name|version)\}/);
+    if (null !== origin && template.lastIndexOf('/', first) < origin[0].length) return 'needs a path before the first placeholder, like https://host/{name}.json';
+    let url;
+    try {
+        url = new URL(template.replaceAll('{name}', 'x').replaceAll('{version}', '1'));
+    } catch  {
+        return 'is not a URL';
+    }
+    if (!isRegistryProtocol(url)) return 'http:' === url.protocol ? 'must be https (http is allowed only for 127.0.0.1, localhost and [::1])' : 'must be an https URL';
+    if ('' !== url.username || '' !== url.password) return 'must not contain a user name or password';
+}
+function registryIndexUrl(template) {
+    const at = template.search(/\{(?:name|version)\}/);
+    const base = template.slice(0, template.lastIndexOf('/', at) + 1);
+    return new URL('index.json', base).href;
+}
+function validateFeatureRegistryIndex(value) {
+    const c = new Checker();
+    if (!isObj(value)) {
+        c.add('', 'must be an object');
+        return c.issues;
+    }
+    const items = value.items;
+    if (!Array.isArray(items)) {
+        c.add('items', 'is required and must be an array');
+        return c.issues;
+    }
+    if (items.length > MAX_INDEX_ITEMS) {
+        c.add('items', `has more than ${String(MAX_INDEX_ITEMS)} items`);
+        return c.issues;
+    }
+    const seen = new Set();
+    items.forEach((item, i)=>{
+        const at = `items[${String(i)}]`;
+        if (!isObj(item)) return void c.add(at, 'must be an object');
+        const name = c.string(item, 'name', at, {
+            pattern: REGISTRY_ITEM_NAME,
+            hint: 'must be a feature name without the namespace, like "analytics-segment"'
+        });
+        if (void 0 !== name) {
+            if (seen.has(name)) c.add(`${at}.name`, `"${name}" is listed twice`);
+            seen.add(name);
+        }
+        c.string(item, 'version', at, {
+            pattern: INDEX_VERSION,
+            hint: 'must be a version like 1.2.0'
+        });
+        const description = c.string(item, "description", at);
+        if (void 0 !== description) {
+            if (description.length > MAX_DESCRIPTION) c.add(`${at}.description`, `must be at most ${String(MAX_DESCRIPTION)} characters`);
+            else if (INVISIBLE.test(description)) c.add(`${at}.description`, 'must be plain text without control characters');
+        }
+        const keywords = c.stringArray(item, 'keywords', at, {
+            required: false
+        });
+        if (keywords.length > MAX_KEYWORDS) c.add(`${at}.keywords`, `must have at most ${String(MAX_KEYWORDS)} entries`);
+        keywords.forEach((keyword, k)=>{
+            if (keyword.length > MAX_KEYWORD || INVISIBLE.test(keyword)) c.add(`${at}.keywords[${String(k)}]`, `must be plain text of at most ${String(MAX_KEYWORD)} characters`);
+        });
+    });
+    return c.issues;
+}
+function isFeatureRegistryIndex(value) {
+    return 0 === validateFeatureRegistryIndex(value).length;
+}
 const project_SEGMENT = String.raw`(?!\.\.?(?:/|$))[^/\\\u0000]+`;
 const CHECKOUT_PATH = new RegExp(`^(?:(?![A-Za-z]:)(?:\\.\\.(?:/\\.\\.)*(?:/${project_SEGMENT})*|${project_SEGMENT}(?:/${project_SEGMENT})*)|(?:/|[A-Za-z]:/)${project_SEGMENT}(?:/${project_SEGMENT})*)$`);
 const FILE_HASH = /^sha256-[0-9a-f]{64}$/;
@@ -519,7 +612,11 @@ function validateMfeflowProject(value) {
         const at = `registries.${ns}`;
         if ('@mfeflow' === ns) c.add(at, '@mfeflow is reserved for first-party features');
         else if (!REGISTRY_NAMESPACE.test(ns)) c.add(at, 'namespaces look like "@someone"');
-        if ('string' != typeof url || !url.startsWith('https://') || !url.includes('{name}')) c.add(at, 'must be an https URL containing {name}');
+        if ('string' != typeof url) c.add(at, 'must be a URL template like "https://example.com/{name}.json"');
+        else {
+            const problem = registryTemplateProblem(url);
+            if (void 0 !== problem) c.add(at, problem);
+        }
     }
     if ('local' in value) {
         const local = c.string(value, 'local', '');
@@ -789,6 +886,9 @@ function validateFeatureManifest(value) {
     c.string(value, "description", '', {
         required: false
     });
+    c.stringArray(value, 'keywords', '', {
+        required: false
+    });
     c.stringArray(value, 'requires', '', {
         required: false,
         pattern: FEATURE_NAME
@@ -868,7 +968,8 @@ const SCHEMA_URLS = {
     project: `${DOCS_URL}/schema/mfeflow.json`,
     feature: `${DOCS_URL}/schema/feature.json`,
     registryEntry: `${DOCS_URL}/schema/registry-entry.json`,
-    registryIndex: `${DOCS_URL}/schema/registry-index.json`
+    registryIndex: `${DOCS_URL}/schema/registry-index.json`,
+    featureRegistryIndex: `${DOCS_URL}/schema/feature-registry-index.json`
 };
 function errorDocsUrl(code) {
     return `${DOCS_URL}/errors/${code}`;
@@ -884,6 +985,7 @@ const json_schema_strings = (pattern)=>({
         type: 'array',
         items: str(pattern)
     });
+const REGISTRY_URL = /^(?:https:\/\/|http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?:[:/?#])).*\{name\}/;
 const literal = {
     type: [
         'string',
@@ -1228,7 +1330,7 @@ const JSON_SCHEMAS = {
                 },
                 additionalProperties: {
                     type: 'string',
-                    pattern: '^https://.*\\{name\\}'
+                    pattern: REGISTRY_URL.source
                 }
             },
             local: str(CHECKOUT_PATH),
@@ -1262,6 +1364,7 @@ const JSON_SCHEMAS = {
             name: str(FEATURE_NAME),
             version: str(),
             description: str(),
+            keywords: json_schema_strings(),
             prompts: {
                 type: 'array',
                 items: json_schema_item({
@@ -1418,6 +1521,37 @@ const JSON_SCHEMAS = {
         required: [
             'remotes'
         ]
+    }),
+    featureRegistryIndex: root('featureRegistryIndex', 'feature registry index', {
+        properties: {
+            items: {
+                type: 'array',
+                maxItems: 1000,
+                items: json_schema_item({
+                    name: str(REGISTRY_ITEM_NAME),
+                    version: str(),
+                    description: {
+                        type: 'string',
+                        maxLength: 300
+                    },
+                    keywords: {
+                        type: 'array',
+                        maxItems: 20,
+                        items: {
+                            type: 'string',
+                            maxLength: 40
+                        }
+                    }
+                }, [
+                    'name',
+                    'version',
+                    "description"
+                ])
+            }
+        },
+        required: [
+            'items'
+        ]
     })
 };
-export { ANALYTICS_EVENT, COST_MODEL, DOCS_URL, EVENT_NAME, EXPOSE, FEATURE_CONDITION, FEATURE_NAME, FILE_HASH, JSON_SCHEMAS, MFE_NAME, ROUTE, SCHEMA_URLS, TRANSFORM_OPS, assetsFromManifest, errorDocsUrl, injectIntoHead, isFeatureManifest, isMfeManifest, isMfeflowProject, isRegistryEntry, isRegistryIndex, isSafeRelativePath, judgeCost, registryInjection, round1, splitScripts, validateFeatureManifest, validateMfeManifest, validateMfeflowProject, validateRegistryEntry, validateRegistryIndex };
+export { ANALYTICS_EVENT, COST_MODEL, DOCS_URL, EVENT_NAME, EXPOSE, FEATURE_CONDITION, FEATURE_NAME, FILE_HASH, JSON_SCHEMAS, MAX_DESCRIPTION, MAX_INDEX_ITEMS, MFE_NAME, REGISTRY_ITEM_NAME, REGISTRY_NAMESPACE, ROUTE, SCHEMA_URLS, TRANSFORM_OPS, assetsFromManifest, errorDocsUrl, injectIntoHead, isFeatureManifest, isFeatureRegistryIndex, isLoopbackHttp, isMfeManifest, isMfeflowProject, isRegistryEntry, isRegistryIndex, isRegistryProtocol, isSafeRelativePath, judgeCost, registryIndexUrl, registryInjection, registryTemplateProblem, round1, splitScripts, validateFeatureManifest, validateFeatureRegistryIndex, validateMfeManifest, validateMfeflowProject, validateRegistryEntry, validateRegistryIndex };

package/dist/json-schema.d.ts

@@ -1,7 +1,7 @@
 import { type SchemaName } from './docs.js';
 type Json = Record<string, unknown>;
 /**
- * Editor schemas for the five JSON documents mfeflow reads. They mirror the validators in this package; the
+ * Editor schemas for the six JSON documents mfeflow reads. They mirror the validators in this package; the
  * validators stay the authority (they also check things a schema cannot, like duplicate routes), so a document
  * can pass here and still fail `mfeflow validate`.
  */

package/dist/project.d.ts

@@ -18,7 +18,7 @@ export interface MfeflowProject {
     }>;
     /** Hashes of copied files, so `upgrade` can tell when a file was edited. */
     files?: Record<string, string>;
-    /** Third-party feature registries: `{ "@someone": "https://…/{name}.json" }`. `@mfeflow` is reserved. */
+    /** Third-party feature registries: `{ "@someone": "https://…/{name}.json" }`, https only (plain http for loopback hosts). `@mfeflow` is reserved. */
     registries?: Record<string, string>;
     /** Built mfeflow checkout, relative to the project root, that `@mfeflow/*` dependencies link to. Set by `--local` only. */
     local?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfeflow/contracts",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Types, validators and JSON Schemas for mfeflow: mfe.json ownership manifests, mfeflow.json project state, and the remote registry (entries and index).",
   "keywords": [
     "micro-frontend",