@aistrike-dev/ui-shell-dev 2.1.0 → 2.1.1

package/dist/devfile.js

@@ -27,22 +27,10 @@ export function assertClaimsInput(value, source) {
     }
     return value;
 }
-function normalizeOverrides(overrides) {
-    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
-        throw new Error('overrides must be an object of id: origin');
-    }
-    const result = {};
-    for (const [id, origin] of Object.entries(overrides)) {
-        if (typeof origin !== 'string') {
-            throw new Error(`override "${id}" must be a string origin`);
-        }
-        const [, normalized] = parseOverride(`${id}=${origin}`);
-        result[id] = normalized;
-    }
-    return result;
-}
-const FILE_KEYS = ['profile', 'overrides', 'domains', 'idleTimeoutMs', 'landing', 'lab', 'claims'];
+const FILE_KEYS = ['domains', 'cell', 'idleTimeoutMs', 'landing', 'lab', 'claims'];
 const DOMAIN_KEYS = ['id', 'nav', 'devPort'];
+const CELL_KEYS = ['domains'];
+const CELL_DOMAIN_KEYS = ['id', 'nav', 'at'];
 const NAV_KEYS = ['label', 'icon'];
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -87,10 +75,10 @@ function validateDomain(value, path) {
     }
     rejectUnknownKeys(value, DOMAIN_KEYS, path);
     const validNav = validateNav(nav, `${path}.nav`);
-    if (!isPort(devPort)) {
+    if (devPort !== undefined && !isPort(devPort)) {
         throw new Error(`${path}.devPort must be an integer from 1 to 65535`);
     }
-    return { id, nav: validNav, devPort };
+    return { id, nav: validNav };
 }
 function validateDomains(value) {
     if (!Array.isArray(value)) {
@@ -98,6 +86,59 @@ function validateDomains(value) {
     }
     return value.map((entry, index) => validateDomain(entry, `domains[${index}]`));
 }
+/** `at`: a port on this machine, or a bare `http:` origin (host, optional port): the dev cell forwards over HTTP. */
+function validateAt(value, id, path) {
+    if (isPort(value)) {
+        return `http://127.0.0.1:${String(value)}`;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${path}.at must be a port or an origin`);
+    }
+    const origin = parseOverride(`${id}=${value}`)[1];
+    if (!origin.startsWith('http:')) {
+        throw new Error(`${path}.at must be an http: origin: the dev cell forwards over HTTP, not "${origin}"`);
+    }
+    return origin;
+}
+function validateCellDomain(value, path) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${path} must be an object`);
+    }
+    rejectUnknownKeys(value, CELL_DOMAIN_KEYS, path);
+    const { id, nav, at } = value;
+    if (typeof id !== 'string' || !isValidDomainId(id)) {
+        throw new Error(`${path}.id must be a DNS label`);
+    }
+    const domain = { id, at: validateAt(at, id, path) };
+    if (nav !== undefined) {
+        domain.nav = validateNav(nav, `${path}.nav`);
+    }
+    return domain;
+}
+/**
+ * The ui-shell dev server's cell. A string would name a deployed cell (KinD, `dev`), which the shell can use only once it
+ * signs in through that cell's identity provider: not yet (cell resolution design 4).
+ */
+function validateCell(value) {
+    if (typeof value === 'string') {
+        throw new Error('cell: a deployed cell needs sign-in through its identity provider, which the shell does not have yet; ' +
+            'list each domain\'s dev server in cell.domains instead');
+    }
+    if (!isPlainObject(value)) {
+        throw new Error('cell must be an object');
+    }
+    rejectUnknownKeys(value, CELL_KEYS, 'cell');
+    if (!Array.isArray(value.domains)) {
+        throw new Error('cell.domains must be an array');
+    }
+    const domains = value.domains.map((entry, index) => validateCellDomain(entry, `cell.domains[${index}]`));
+    const ids = domains.map((domain) => domain.id);
+    const twice = ids.find((id, index) => ids.indexOf(id) !== index);
+    if (twice !== undefined) {
+        throw new Error(`cell.domains lists "${twice}" twice`);
+    }
+    return { domains };
+}
 function validateIdle(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
         throw new Error('idleTimeoutMs must be a finite number of at least 0');
@@ -148,20 +189,21 @@ function validateFile(parsed, name) {
         if (!isPlainObject(parsed)) {
             throw new Error('must be a JSON object');
         }
-        rejectUnknownKeys(parsed, FILE_KEYS, '');
-        const result = {};
-        if (parsed.profile !== undefined) {
-            if (typeof parsed.profile !== 'string') {
-                throw new Error('profile must be a string');
-            }
-            result.profile = parsed.profile;
+        if ('profile' in parsed) {
+            throw new Error('profile is no longer read; delete it: every domain is loaded from the dev host, which forwards it');
         }
-        if (parsed.overrides !== undefined) {
-            result.overrides = normalizeOverrides(parsed.overrides);
+        if ('overrides' in parsed) {
+            throw new Error('overrides is no longer read; delete it: an MFE project runs the built-in MFEs and its own, and the ' +
+                'ui-shell dev server\'s cell.domains says where other domains run');
         }
+        rejectUnknownKeys(parsed, FILE_KEYS, '');
+        const result = {};
         if (parsed.domains !== undefined) {
             result.domains = validateDomains(parsed.domains);
         }
+        if (parsed.cell !== undefined) {
+            result.cell = validateCell(parsed.cell);
+        }
         return readExtras(parsed, result);
     }
     catch (error) {
@@ -193,12 +235,15 @@ function landingOf(file, args) {
 function labOf(file) {
     return file?.lab === undefined ? {} : { lab: file.lab !== false };
 }
-/** Explicit overrides win over the file; the profile defaults to `local`; the idle timeout defaults to off for local work. */
+/**
+ * What the shell is told: the domains it does not compile in (by name; where they run stays here), the landing route,
+ * the lab and the session. An explicit landing wins over the file; the idle timeout defaults to off for local work.
+ */
 export function buildDevConfig(file, args, session) {
+    const all = [...(file?.domains ?? []), ...(file?.cell?.domains ?? [])];
+    const named = all.flatMap(({ id, nav }) => (nav === undefined ? [] : [{ id, nav }]));
     return {
-        profile: args.profile ?? file?.profile ?? 'local',
-        overrides: { ...(file?.overrides ?? {}), ...args.overrides },
-        domains: file?.domains ?? [],
+        domains: named,
         idleTimeoutMs: file?.idleTimeoutMs ?? 0,
         landing: landingOf(file, args),
         ...labOf(file),

package/dist/hosts.d.ts

@@ -0,0 +1,17 @@
+import type { ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+export declare const REFUSED_HOST: string;
+/**
+ * The `Host`s a dev server answers, as Vite's default `allowedHosts` does: `localhost`, `*.localhost`, and IP literals
+ * (IPv4, bracketed IPv6), each with or without a port. Any other name could be a DNS-rebinding page, which would read
+ * the dev token the console hands out and everything the dev cell forwards.
+ */
+export declare function isAllowedHost(host: string | undefined): host is string;
+/** Answers a request whose `Host` is not allowed. */
+export declare function refuseHost(res: ServerResponse): void;
+/** Answers a WebSocket upgrade whose `Host` is not allowed. */
+export declare function refuseUpgradeHost(socket: Duplex): void;
+/** How many dev tokens a dev server keeps, one per address a browser reached it by. */
+export declare const MAX_SESSIONS = 32;
+/** Keeps `value` for `key`, letting the oldest entry go once `MAX_SESSIONS` are kept. */
+export declare function rememberSession<T>(sessions: Map<string, T>, key: string, value: T): void;

package/dist/hosts.js

@@ -0,0 +1,51 @@
+import { isIP } from 'node:net';
+const PORT = /^\d{1,5}$/;
+export const REFUSED_HOST = 'This dev server answers only localhost and IP addresses. ' +
+    'Open it at localhost or this machine\'s address.';
+/** `localhost`, a name under it, or an IP literal (IPv6 in brackets). */
+function isLocalName(name) {
+    if (name.startsWith('[')) {
+        return name.endsWith(']') && isIP(name.slice(1, -1)) === 6;
+    }
+    return isIP(name) === 4 || name === 'localhost' || (name.endsWith('.localhost') && name.length > '.localhost'.length);
+}
+/**
+ * The `Host`s a dev server answers, as Vite's default `allowedHosts` does: `localhost`, `*.localhost`, and IP literals
+ * (IPv4, bracketed IPv6), each with or without a port. Any other name could be a DNS-rebinding page, which would read
+ * the dev token the console hands out and everything the dev cell forwards.
+ */
+export function isAllowedHost(host) {
+    if (host === undefined) {
+        return false;
+    }
+    const value = host.trim().toLowerCase();
+    const split = value.startsWith('[') ? value.indexOf(']') + 1 : value.indexOf(':');
+    if (split === 0) {
+        return false;
+    }
+    const name = split === -1 ? value : value.slice(0, split);
+    const port = split === -1 ? '' : value.slice(split);
+    return (port === '' || (port.startsWith(':') && PORT.test(port.slice(1)))) && isLocalName(name);
+}
+/** Answers a request whose `Host` is not allowed. */
+export function refuseHost(res) {
+    res.statusCode = 403;
+    res.setHeader('Content-Type', 'text/plain');
+    res.end(REFUSED_HOST);
+}
+/** Answers a WebSocket upgrade whose `Host` is not allowed. */
+export function refuseUpgradeHost(socket) {
+    socket.end(`HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\n${REFUSED_HOST}`);
+}
+/** How many dev tokens a dev server keeps, one per address a browser reached it by. */
+export const MAX_SESSIONS = 32;
+/** Keeps `value` for `key`, letting the oldest entry go once `MAX_SESSIONS` are kept. */
+export function rememberSession(sessions, key, value) {
+    if (sessions.size >= MAX_SESSIONS) {
+        const oldest = sessions.keys().next();
+        if (oldest.done !== true) {
+            sessions.delete(oldest.value);
+        }
+    }
+    sessions.set(key, value);
+}

package/dist/inject.js

@@ -17,9 +17,6 @@ export const CONTENT_TYPES = {
     '.txt': 'text/plain; charset=utf-8',
 };
 export function validateDevConfig(devConfig) {
-    if (devConfig.profile === undefined || devConfig.profile === '') {
-        throw new Error('dev config must name a profile');
-    }
     if (devConfig.session !== undefined && !(devConfig.session.expiresAt > Date.now())) {
         throw new Error('dev session is already expired; mint a new token');
     }

package/dist/platform/host.d.ts

@@ -1,4 +1,4 @@
-/** A platform MFE the package carries, and the port the shell's `local` profile looks for it on. */
+/** A platform MFE the package carries, and the port the dev host forwards its paths to. */
 export interface PlatformEntry {
     id: string;
     devPort: number;
@@ -9,10 +9,8 @@ export interface PlatformLogger {
 }
 export interface SelectOptions {
     ownId: string;
-    profile: string;
-    overrides: {
-        [id: string]: string;
-    };
+    /** Domains another server serves (the ui-shell dev server's `cell.domains`): never bundled. */
+    elsewhere: readonly string[];
     option: boolean | string[] | undefined;
 }
 export interface PlatformHost {
@@ -26,8 +24,8 @@ export interface PlatformHost {
 /** `<platformDir>/platform.json`, keeping the entries whose build is present. A missing or broken list is none. */
 export declare function readPlatform(platformDir: string): PlatformEntry[];
 /**
- * Platform-MFE spec 3.3 step 1: never the MFE being developed (it is this server), never a domain the dev file points
- * elsewhere, nothing outside the `local` profile (the shell would not look at local ports), and what the option allows.
+ * Platform-MFE spec 3.3 step 1: never the MFE being developed (it is this server), never a domain another server serves,
+ * and what the option allows.
  */
 export declare function selectPlatform(entries: PlatformEntry[], options: SelectOptions): PlatformEntry[];
 /**

package/dist/platform/host.js

@@ -24,16 +24,16 @@ export function readPlatform(platformDir) {
     return parsed.filter((entry) => existsSync(join(platformDir, entry.id, 'ui', 'manifest.json')));
 }
 /**
- * Platform-MFE spec 3.3 step 1: never the MFE being developed (it is this server), never a domain the dev file points
- * elsewhere, nothing outside the `local` profile (the shell would not look at local ports), and what the option allows.
+ * Platform-MFE spec 3.3 step 1: never the MFE being developed (it is this server), never a domain another server serves,
+ * and what the option allows.
  */
 export function selectPlatform(entries, options) {
-    if (options.option === false || options.profile !== 'local') {
+    if (options.option === false) {
         return [];
     }
     const allowed = Array.isArray(options.option) ? options.option : undefined;
     return entries.filter((entry) => entry.id !== options.ownId
-        && !(entry.id in options.overrides)
+        && !options.elsewhere.includes(entry.id)
         && (allowed === undefined || allowed.includes(entry.id)));
 }
 const errorCode = (error) => error?.code;

package/dist/platform/list.d.ts

@@ -1,6 +1,6 @@
 import type { PackagedEntry } from './copy.js';
 /**
- * The platform MFEs the package carries (platform-MFE spec 3.1), each on the `devPort` of the shell's domain list
- * (`list.test.ts` pins them). The copy script writes this to `platform/platform.json`. Never the lab: it is dev-only.
+ * The platform MFEs the package carries (platform-MFE spec 3.1), each on its port in `DEV_PORTS`. The copy script writes
+ * this to `platform/platform.json`. Never the lab: it is dev-only.
  */
 export declare const PLATFORM: readonly PackagedEntry[];

package/dist/platform/list.js

@@ -1,9 +1,10 @@
+import { DEV_PORTS } from '../ports.js';
 /**
- * The platform MFEs the package carries (platform-MFE spec 3.1), each on the `devPort` of the shell's domain list
- * (`list.test.ts` pins them). The copy script writes this to `platform/platform.json`. Never the lab: it is dev-only.
+ * The platform MFEs the package carries (platform-MFE spec 3.1), each on its port in `DEV_PORTS`. The copy script writes
+ * this to `platform/platform.json`. Never the lab: it is dev-only.
  */
 export const PLATFORM = [
-    { id: 'assistant', devPort: 5104, mock: true },
-    { id: 'settings', devPort: 5101, mock: true },
-    { id: 'home', devPort: 5102, mock: false },
+    { id: 'assistant', devPort: DEV_PORTS.assistant, mock: true },
+    { id: 'settings', devPort: DEV_PORTS.settings, mock: true },
+    { id: 'home', devPort: DEV_PORTS.home, mock: false },
 ];

package/dist/platform/server.d.ts

@@ -8,7 +8,8 @@ export interface PlatformServerOptions {
     handlers: MockHandler[];
 }
 /**
- * One bundled platform MFE, served as its own dev server would be on its own port: same-host CORS, the build at
- * `/ui/latest/` (no redirect; the resolver accepts a manifest at `latest`, as from a dev server) and the mocks at `/api/`.
+ * One bundled platform MFE, served as its own dev server would be on its own port, in the cell's layout (cell resolution
+ * design 3): same-host CORS, the build at `/<id>/ui/latest/` (no redirect; the resolver accepts a manifest at `latest`,
+ * as from a dev server) and the mocks at `/<id>/api/`, which reach them as `/api/`.
  */
 export declare function createPlatformServer(options: PlatformServerOptions): Server;

package/dist/platform/server.js

@@ -2,18 +2,28 @@ import { createServer } from 'node:http';
 import { normalize, resolve, sep } from 'node:path';
 import { sendFile } from '../inject.js';
 import { sameHostCors } from './cors.js';
-const UI = '/ui/latest/';
 function answer(res, status, text) {
     res.statusCode = status;
     res.setHeader('Content-Type', 'text/plain');
     res.end(text);
 }
+/** The file in the build a path under `ui` names, or `null` for one outside it (`..` included). */
+function buildFile(uiDir, ui, pathname) {
+    if (!pathname.startsWith(ui)) {
+        return null;
+    }
+    const target = resolve(uiDir, `.${normalize(`/${pathname.slice(ui.length)}`)}`);
+    return target.startsWith(uiDir + sep) ? target : null;
+}
 /**
- * One bundled platform MFE, served as its own dev server would be on its own port: same-host CORS, the build at
- * `/ui/latest/` (no redirect; the resolver accepts a manifest at `latest`, as from a dev server) and the mocks at `/api/`.
+ * One bundled platform MFE, served as its own dev server would be on its own port, in the cell's layout (cell resolution
+ * design 3): same-host CORS, the build at `/<id>/ui/latest/` (no redirect; the resolver accepts a manifest at `latest`,
+ * as from a dev server) and the mocks at `/<id>/api/`, which reach them as `/api/`.
  */
 export function createPlatformServer(options) {
     const uiDir = resolve(options.uiDir);
+    const ui = `/${options.id}/ui/latest/`;
+    const api = `/${options.id}/api/`;
     return createServer((req, res) => {
         if (sameHostCors(req, res)) {
             return;
@@ -26,18 +36,19 @@ export function createPlatformServer(options) {
             answer(res, 400, 'bad request');
             return;
         }
-        if (pathname.startsWith('/api/')) {
+        const raw = req.url ?? '/';
+        if (raw.startsWith(api)) {
+            // The mocks see what a service behind a cell's route sees: the path without its domain prefix.
+            req.url = `/api/${raw.slice(api.length)}`;
             if (!options.handlers.some((handle) => handle(req, res))) {
                 answer(res, 404, 'not found');
             }
             return;
         }
-        if (pathname.startsWith(UI) && (req.method === 'GET' || req.method === 'HEAD')) {
-            const target = resolve(uiDir, `.${normalize(`/${pathname.slice(UI.length)}`)}`);
-            if (target.startsWith(uiDir + sep)) {
-                sendFile(target, res);
-                return;
-            }
+        const target = req.method === 'GET' || req.method === 'HEAD' ? buildFile(uiDir, ui, pathname) : null;
+        if (target !== null) {
+            sendFile(target, res);
+            return;
         }
         answer(res, 404, 'not found');
     });

package/dist/ports.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Where each compiled domain's dev server listens (cell resolution design 3). The shell knows no ports: it loads every
+ * domain from `<the dev host>/<id>`, and the dev host forwards there. `ports.test.ts` keeps these ids equal to the
+ * shell's compiled domain list and each port equal to the domain's own `mfe({ devPort })`.
+ */
+export declare const DEV_PORTS: {
+    readonly home: 5102;
+    readonly settings: 5101;
+    readonly assistant: 5104;
+};
+/** The port of a compiled domain, or `undefined` for any other id. */
+export declare function devPortOf(id: string): number | undefined;

package/dist/ports.js

@@ -0,0 +1,14 @@
+/**
+ * Where each compiled domain's dev server listens (cell resolution design 3). The shell knows no ports: it loads every
+ * domain from `<the dev host>/<id>`, and the dev host forwards there. `ports.test.ts` keeps these ids equal to the
+ * shell's compiled domain list and each port equal to the domain's own `mfe({ devPort })`.
+ */
+export const DEV_PORTS = {
+    home: 5102,
+    settings: 5101,
+    assistant: 5104,
+};
+/** The port of a compiled domain, or `undefined` for any other id. */
+export function devPortOf(id) {
+    return Object.hasOwn(DEV_PORTS, id) ? DEV_PORTS[id] : undefined;
+}

package/dist/preamble.d.ts

@@ -0,0 +1,15 @@
+/** Where `@vitejs/plugin-react` serves React Refresh's runtime on a dev server whose Vite base is `/<id>/ui/latest/`. */
+export declare function refreshRuntimePath(id: string): string;
+/**
+ * Whether a domain's server is a Vite dev server with `@vitejs/plugin-react`: it serves React Refresh's runtime. Its
+ * component modules then refuse to run unless the page installed the runtime's preamble.
+ */
+export declare function servesRefreshRuntime(origin: string, id: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * The preamble `@vitejs/plugin-react` writes into the page its own Vite server serves, for a page another server serves
+ * (the ui-shell console): one module script per runtime URL, each installing that runtime into React's global hook.
+ * Each MFE bundles its own React, so each dev server's runtime registers its own components.
+ */
+export declare function refreshPreamble(runtimeUrls: readonly string[]): string;
+/** Puts `snippet` before the page's first module script, so it runs before the shell's entry. */
+export declare function beforeFirstModule(html: string, snippet: string, source: string): string;

package/dist/preamble.js

@@ -0,0 +1,44 @@
+import { escapeJsonForScript } from './escape.js';
+/** Where `@vitejs/plugin-react` serves React Refresh's runtime on a dev server whose Vite base is `/<id>/ui/latest/`. */
+export function refreshRuntimePath(id) {
+    return `/${id}/ui/latest/@react-refresh`;
+}
+/**
+ * Whether a domain's server is a Vite dev server with `@vitejs/plugin-react`: it serves React Refresh's runtime. Its
+ * component modules then refuse to run unless the page installed the runtime's preamble.
+ */
+export async function servesRefreshRuntime(origin, id, timeoutMs = 1000) {
+    try {
+        const res = await fetch(`${origin}${refreshRuntimePath(id)}`, { signal: AbortSignal.timeout(timeoutMs) });
+        await res.body?.cancel();
+        return res.ok && (res.headers.get('content-type') ?? '').includes('javascript');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The preamble `@vitejs/plugin-react` writes into the page its own Vite server serves, for a page another server serves
+ * (the ui-shell console): one module script per runtime URL, each installing that runtime into React's global hook.
+ * Each MFE bundles its own React, so each dev server's runtime registers its own components.
+ */
+export function refreshPreamble(runtimeUrls) {
+    return runtimeUrls.map((url) => [
+        '<script type="module">',
+        `import RefreshRuntime from ${escapeJsonForScript(JSON.stringify(url))};`,
+        'RefreshRuntime.injectIntoGlobalHook(window);',
+        'window.$RefreshReg$ = () => {};',
+        'window.$RefreshSig$ = () => (type) => type;',
+        'window.__vite_plugin_react_preamble_installed__ = true;',
+        '</script>',
+    ].join('\n')).join('\n');
+}
+/** Puts `snippet` before the page's first module script, so it runs before the shell's entry. */
+export function beforeFirstModule(html, snippet, source) {
+    const marker = '<script type="module"';
+    const at = html.indexOf(marker);
+    if (at === -1) {
+        throw new Error(`${source} has no module script to inject before`);
+    }
+    return snippet === '' ? html : `${html.slice(0, at)}${snippet}\n    ${html.slice(at)}`;
+}

package/dist/serve.d.ts

@@ -0,0 +1,28 @@
+import { type PlatformLogger } from './platform/host.js';
+export declare const DEFAULT_CONSOLE_PORT = 3000;
+export declare const DEFAULT_CELL_PORT = 4000;
+export interface ServeOptions {
+    /** The shell's devhost build. */
+    shellDir: string;
+    /** The platform MFEs' builds. */
+    platformDir: string;
+    /** The dev file, relative to `cwd`. Default `shell.dev.json`. */
+    config?: string;
+    cwd: string;
+    port?: number;
+    cellPort?: number;
+    /** Where the dev key lives. Default: the user's config directory. */
+    keyDir?: string;
+    logger: PlatformLogger;
+}
+export interface Serving {
+    consolePort: number;
+    cellPort: number;
+    close: () => Promise<void>;
+}
+/**
+ * The ui-shell dev server (cell resolution design 3): the console, which serves the shell's devhost build with a dev
+ * token, and the dev cell, an origin of its own that forwards each domain to the server its `cell.domains` names, or
+ * to the built-in MFE. The shell loads every domain from the cell, cross-origin, as from a deployed cell.
+ */
+export declare function serveDevShell(options: ServeOptions): Promise<Serving>;