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

package/README.md

@@ -16,26 +16,40 @@ export default defineConfig({
 });
 ```
 
-`vite` now serves the shell at `/` with a minted dev session, and your MFE at `/ui/latest/`, on one origin, with HMR.
-Other domains resolve by the profile's convention unless `shell.dev.json` overrides them.
+`vite` now runs the shell as it is deployed: a **console** and a **cell** on two origins.
+
+- The console is your Vite server: the shell at `/` with a minted dev session.
+- The cell is a server on its own port: the console's plus 1000 (5103 → 6103), or any free port when that is past 65535
+  or taken. `shellDevHost({ cellPort })` pins it; a pinned port that is taken is logged and the cell does not start. It
+  forwards each domain's `/<id>/ui/…` and `/<id>/api/…`, WebSockets included, to the server that has it: your MFE
+  (this Vite server) and the built-in MFEs, nothing else.
+- The dev token's `cell` claim names the cell on the address the browser used, so the shell loads every domain from it
+  cross-origin, with CORS and the bearer token, exactly as from `https://<cell>/<id>` when deployed. Your MFE's HMR runs
+  through the cell too.
+
+Your dev server serves the cell's layout: `mfe()` puts the MFE under the Vite base `/<id>/ui/latest/` and answers
+`/<id>/api/…` as `/api/…`, so your mock API keeps its `/api/` paths.
+
+To see your MFE beside other domains' dev servers, use the ui-shell repository's dev server
+(`pnpm --filter @aistrike-dev/ui-shell dev`), whose cell forwards to every server its `shell.dev.json` lists.
 
 ## Built-in MFEs
 
 The package carries prebuilt copies of the MFEs that ship with the shell (assistant, settings and home) with their mock
-APIs, and the plugin serves each on the port the shell looks for it on: assistant 5104, settings 5101, home 5102. You
-get the whole frame (Home, Settings, the assistant pane on ⌘I / Ctrl+I) with nothing else running.
+APIs, and the plugin serves each on its port (assistant 5104, settings 5101, home 5102), behind the cell. You get the
+whole frame (Home, Settings, the assistant pane on ⌘I / Ctrl+I) with nothing else running.
 
 - A server already listening on one of those ports wins: the plugin leaves that port alone, so a real dev server for
   that MFE (with HMR) is used instead. A port freed later is taken over on the next page load.
 - A real dev server for one of them started *after* this one fails, because the bundled copy holds its port. Start the
   one you are editing first, or restart this server after starting it.
-- `shellDevHost({ platform: false })` serves none; `shellDevHost({ platform: ['assistant'] })` only those listed. A
-  domain that `shell.dev.json` overrides, or any profile other than `local`, is never bundled.
+- `shellDevHost({ platform: false })` serves none; `shellDevHost({ platform: ['assistant'] })` only those listed.
 - The copies are as old as the package (in this repository, the last `pnpm nx build dev-host`).
 
-Keep Vite's `server.allowedHosts` at its default: the plugin derives your MFE's origin from the request's `Host`
-header, which is only safe while Vite rejects unknown hosts. With `server.https` Vite skips host validation, so the
-self-override trusts the `Host` header as-is.
+Keep Vite's `server.allowedHosts` at its default: the plugin names the cell in the dev token on the request's `Host`
+address, which is only safe while Vite rejects unknown hosts. The cell applies the same rule itself: it answers only a
+`Host` of `localhost`, `*.localhost` or an IP address, and `403` to anything else. The cell is plain HTTP, so serve the
+console over HTTP too: the shell loads the cell over the console's own protocol.
 
 ## `shell.dev.json`
 
@@ -43,19 +57,19 @@ Read from the Vite root when present (or from the plugin's `devFile` option).
 
 ```json
 {
-  "profile": "local",
-  "overrides": { "other": "http://127.0.0.1:5102" },
-  "domains": [{ "id": "other", "nav": { "label": "Other" }, "devPort": 5102 }],
+  "domains": [{ "id": "hello", "nav": { "label": "Hello" } }],
   "idleTimeoutMs": 0,
   "claims": { "permissions": ["hello:read"] }
 }
 ```
 
-A domain's route prefix is always `/<id>`, so a domain has no `route` key: a leftover one stops the dev server with a message to delete it. The ids `shell`, `preferences`, `commands`, `api`, `assets` and `ui` are reserved.
+A domain's route prefix is always `/<id>`, so a domain has no `route` key, and the shell has no profiles, so the file
+has no `profile` key: a leftover one of either stops the dev server with a message to delete it. The ids `shell`,
+`preferences`, `commands`, `api`, `assets`, `ui`, `config`, `signin` and `webhooks` are reserved.
 
-`profile` defaults to `local`, `overrides` point other domains at their own dev servers (bare origins, no path; your
-own domain is overridden automatically), `idleTimeoutMs` defaults to `0` (idle timeout off), and `claims` is merged
-over the default dev claims. The plugin's `claims`, `ttlMs` and `noToken` options win over the file. `"lab": true`
+`domains` names your own domain when the shell does not compile it in (a `devPort` is accepted and ignored); naming
+another domain, or an `overrides` or `cell` key, stops the dev server. `idleTimeoutMs` defaults to `0` (idle timeout off), and `claims` is merged
+over the default dev claims (`cell` is the plugin's, not the file's). The plugin's `claims`, `ttlMs` and `noToken` options win over the file. `"lab": true`
 shows Octopus UI's Design Lab (its live controls for the open design questions, in a Picture-in-Picture window) over
 your pages, so you can judge them on your own screens. `"lab": { "designSystem": "../octopus-ui" }` also names an
 Octopus checkout (relative to the Vite root): **Lock in** then writes a work-loop item into its `.backlog/`, through
@@ -72,7 +86,17 @@ aistrike-shell token [--claims <path>] [--ttl 30d|12h|45m|90s] [--out <path>] [-
 
 The package's own e2e (`pnpm nx e2e dev-host`) serves the settings MFE on port 5101, with the bundled home and assistant on 5102 and 5104; it fails loudly if a dev server already occupies 5101, and stop any on 5102 or 5104 first. It also checks that `npm pack` would publish the bundled copies.
 
-Opening `/` in dev lands on your own MFE (the plugin injects `landing` with your domain id; `shell.dev.json` may set `landing` to another domain id; an id that is not in the shell's domain list falls back to `/home`). A domain in the profile that is neither bundled nor running shows as failed in the rail.
+Opening `/` in dev lands on your own MFE (the plugin injects `landing` with your domain id; `shell.dev.json` may set `landing` to another domain id; an id that is not in the shell's domain list falls back to `/home`). A domain that is neither bundled nor running shows as failed in the rail.
+
+```
+aistrike-shell serve --shell-dir <devhost build> [--config shell.dev.json] [--port 3000] [--cell-port 4000]
+```
+
+`serve` is the ui-shell repository's dev server: the console and a cell whose `shell.dev.json` lists where each domain
+runs, `{ "cell": { "domains": [{ "id": "lab", "nav": { "label": "Lab" }, "at": 5103 }] } }` (`at` a port or an `http:` origin:
+the cell forwards over HTTP; `nav` only for a domain the shell does not compile in). Its console and cell answer only
+`localhost`, `*.localhost` and IP addresses. Every compiled domain not listed is the built-in MFE. A deployed
+cell (`"cell": "https://…"`) is refused until the shell can sign in to it.
 
 ## Checking Fast Refresh (spike 1)
 

package/dist/args.d.ts

@@ -1,10 +1,18 @@
-export declare const USAGE = "Usage: aistrike-shell token [options]\n\nMint a dev token for local back ends.\n  --claims <path>           JSON claims for the token\n  --ttl <30d|12h|45m|90s>   token lifetime (default 30d)\n  --out <path>              also write the token to a file (mode 0600)\n  --json                    print { token, session } instead of the bare token\n\nThe shell itself is served by shellDevHost() from @aistrike-dev/ui-shell-dev/vite:\nadd it to your MFE's vite.config.ts after mfe(), and \"vite\" serves the shell at /.\nShell settings (profile, overrides, domains, claims) live in shell.dev.json.\n";
+export declare const USAGE = "Usage: aistrike-shell token [options]\n       aistrike-shell serve [options]\n\ntoken: mint a dev token for local back ends.\n  --claims <path>           JSON claims for the token\n  --ttl <30d|12h|45m|90s>   token lifetime (default 30d)\n  --out <path>              also write the token to a file (mode 0600)\n  --json                    print { token, session } instead of the bare token\n\nserve: the ui-shell dev server: the console, and a dev cell that forwards each\ndomain to the dev server shell.dev.json's cell.domains names, or to the\nbuilt-in MFE.\n  --shell-dir <path>        the shell's devhost build (required)\n  --config <path>           the dev file (default shell.dev.json)\n  --port <n>                the console's port (default 3000)\n  --cell-port <n>           the cell's port (default 4000)\n\nIn an MFE project the shell is served by shellDevHost() from\n@aistrike-dev/ui-shell-dev/vite: add it to your vite.config.ts after mfe(), and\n\"vite\" serves the shell at / beside a dev cell. Settings live in shell.dev.json.\n";
 export declare const DOMAIN_ID: RegExp;
 export declare const RESERVED_DOMAIN_IDS: ReadonlySet<string>;
 export declare function isValidDomainId(id: string): boolean;
 export declare function parseTtl(text: string): number;
 /** `id=origin`. The origin must be a bare origin: scheme, host, optional port, nothing else (spec 4.5). */
 export declare function parseOverride(text: string): [string, string];
+export interface ServeArgs {
+    shellDir?: string;
+    config?: string;
+    port?: number;
+    cellPort?: number;
+    help: boolean;
+}
+export declare function parseServeArgs(argv: string[]): ServeArgs;
 export interface TokenArgs {
     claims?: string;
     ttl?: string;

package/dist/args.js

@@ -1,21 +1,32 @@
 export const USAGE = `Usage: aistrike-shell token [options]
+       aistrike-shell serve [options]
 
-Mint a dev token for local back ends.
+token: mint a dev token for local back ends.
   --claims <path>           JSON claims for the token
   --ttl <30d|12h|45m|90s>   token lifetime (default 30d)
   --out <path>              also write the token to a file (mode 0600)
   --json                    print { token, session } instead of the bare token
 
-The shell itself is served by shellDevHost() from @aistrike-dev/ui-shell-dev/vite:
-add it to your MFE's vite.config.ts after mfe(), and "vite" serves the shell at /.
-Shell settings (profile, overrides, domains, claims) live in shell.dev.json.
+serve: the ui-shell dev server: the console, and a dev cell that forwards each
+domain to the dev server shell.dev.json's cell.domains names, or to the
+built-in MFE.
+  --shell-dir <path>        the shell's devhost build (required)
+  --config <path>           the dev file (default shell.dev.json)
+  --port <n>                the console's port (default 3000)
+  --cell-port <n>           the cell's port (default 4000)
+
+In an MFE project the shell is served by shellDevHost() from
+@aistrike-dev/ui-shell-dev/vite: add it to your vite.config.ts after mfe(), and
+"vite" serves the shell at / beside a dev cell. Settings live in shell.dev.json.
 `;
 const TTL = /^(\d+)([dhms])$/;
 const UNIT_MS = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1000 };
 // Mirrors the contract's DNS-label rule for domain ids. Duplicated (not imported) so the dev host has no runtime dependencies.
 export const DOMAIN_ID = /^[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 // Mirrors the SDK's RESERVED_DOMAIN_IDS, duplicated for the same reason as DOMAIN_ID.
-export const RESERVED_DOMAIN_IDS = new Set(['shell', 'preferences', 'commands', 'api', 'assets', 'ui']);
+export const RESERVED_DOMAIN_IDS = new Set([
+    'shell', 'preferences', 'commands', 'api', 'assets', 'ui', 'config', 'signin', 'webhooks',
+]);
 export function isValidDomainId(id) {
     return DOMAIN_ID.test(id) && !RESERVED_DOMAIN_IDS.has(id);
 }
@@ -64,6 +75,41 @@ function takeValue(argv, index, flag) {
     }
     return value;
 }
+function parsePort(text, flag) {
+    const port = Number(text);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${flag} must be a port from 1 to 65535`);
+    }
+    return port;
+}
+export function parseServeArgs(argv) {
+    const args = { help: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const flag = argv[i];
+        if (flag === '--help') {
+            args.help = true;
+            continue;
+        }
+        const value = takeValue(argv, i, flag);
+        i += 1;
+        if (flag === '--shell-dir') {
+            args.shellDir = value;
+        }
+        else if (flag === '--config') {
+            args.config = value;
+        }
+        else if (flag === '--port') {
+            args.port = parsePort(value, flag);
+        }
+        else if (flag === '--cell-port') {
+            args.cellPort = parsePort(value, flag);
+        }
+        else {
+            throw new Error(`unknown option "${flag}"`);
+        }
+    }
+    return args;
+}
 const TOKEN_VALUE_FLAGS = new Map([['--claims', 'claims'], ['--ttl', 'ttl'], ['--out', 'out']]);
 export function parseTokenArgs(argv) {
     const args = { json: false, help: false };

package/dist/cell.d.ts

@@ -0,0 +1,29 @@
+import { type Server } from 'node:http';
+export interface CellLogger {
+    warn: (msg: string) => void;
+}
+export interface CellOptions {
+    /** Where each domain runs: id → origin (`http://127.0.0.1:5104`). The cell forwards that domain's paths there. */
+    targets: () => ReadonlyMap<string, string>;
+    logger: CellLogger;
+}
+/** The domain a request is for, when its path is a domain's UI or API. */
+export declare function domainOf(url: string | undefined): string | null;
+/** The dev cell's server. */
+export interface CellServer extends Server {
+    /**
+     * Destroys every upgraded connection (a forwarded WebSocket, both its sides). `close()` waits for them and
+     * `closeAllConnections()` does not reach them, so without this a cell with an open HMR socket never closes.
+     */
+    destroyUpgrades: () => void;
+}
+/** Closes the cell and every connection it holds, upgraded ones included. */
+export declare function closeCell(cell: CellServer): Promise<void>;
+/**
+ * The dev cell (cell resolution design 3): an origin of its own, as a deployed cell is, that answers each domain's
+ * `/<id>/ui/…` and `/<id>/api/…` by forwarding to the server that has it, with the path and `Host` unchanged and
+ * WebSocket upgrades included. The shell loads every domain from here, cross-origin, as it does from a deployed cell;
+ * the servers behind it answer CORS for the console's origin. Anything else is 404, and a `Host` that is not
+ * `localhost` or an IP address is 403 (`isAllowedHost`).
+ */
+export declare function createCellServer(options: CellOptions): CellServer;

package/dist/cell.js

@@ -0,0 +1,194 @@
+import { createServer, request } from 'node:http';
+import { isAllowedHost, refuseHost, refuseUpgradeHost } from './hosts.js';
+/**
+ * A domain's paths on a cell: its UI and its API (addressing standard, micro front-end and API paths). Every other path
+ * is not the cell's.
+ */
+const DOMAIN_PATH = /^\/([a-z](?:[a-z0-9-]{0,61}[a-z0-9])?)\/(?:ui|api)(?:[/?#]|$)/;
+/** The domain a request is for, when its path is a domain's UI or API. */
+export function domainOf(url) {
+    return DOMAIN_PATH.exec(url ?? '')?.[1] ?? null;
+}
+function answer(res, status, text) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'text/plain');
+    res.end(text);
+}
+function forward(req, res, target, logger) {
+    const failed = (error) => {
+        logger.warn(`cell: ${req.url ?? ''} → ${target.origin}: ${error.message}`);
+        if (!res.headersSent) {
+            answer(res, 502, `nothing answers at ${target.origin}`);
+        }
+        else {
+            res.destroy();
+        }
+    };
+    let upstream;
+    try {
+        upstream = request({ protocol: target.protocol, hostname: target.hostname, port: target.port, method: req.method, path: req.url, headers: req.headers }, (reply) => {
+            res.writeHead(reply.statusCode ?? 502, reply.headers);
+            // The domain's server went away before its answer ended (a dev server that restarts during a stream of
+            // server-sent events): so does the browser's, which then reconnects. `pipe` alone would leave it open.
+            reply.on('error', (error) => {
+                logger.warn(`cell: ${req.url ?? ''} → ${target.origin}: ${error.message}`);
+                res.destroy();
+            });
+            reply.on('close', () => {
+                if (!reply.complete) {
+                    res.destroy();
+                }
+            });
+            reply.pipe(res);
+        });
+    }
+    catch (error) {
+        // A target `node:http` cannot reach (an `https:` origin) throws here, not on 'error'.
+        failed(error instanceof Error ? error : new Error(String(error)));
+        return;
+    }
+    // The browser went away before the answer ended (a closed tab, a stream such as server-sent events): so does the
+    // request behind it, which would otherwise stay open on the domain's server.
+    let gone = false;
+    res.on('close', () => {
+        if (!res.writableFinished) {
+            gone = true;
+            upstream.destroy();
+        }
+    });
+    upstream.on('error', (error) => {
+        if (!gone) {
+            failed(error);
+        }
+    });
+    req.on('error', () => {
+        upstream.destroy();
+    });
+    req.pipe(upstream);
+}
+/**
+ * Forwards a WebSocket upgrade (a dev server's HMR) and then the raw bytes both ways. Node removes its own `error`
+ * listener from the browser's socket before it emits `upgrade`, so this one is attached first: a browser that resets
+ * the connection before the domain's server answers would otherwise end the process. Whichever side closes or fails,
+ * both are destroyed.
+ */
+function forwardUpgrade(req, socket, head, target, track) {
+    let upstream = null;
+    let upstreamSocket = null;
+    const teardown = () => {
+        upstream?.destroy();
+        upstreamSocket?.destroy();
+        socket.destroy();
+    };
+    socket.on('error', teardown);
+    socket.on('close', teardown);
+    const refuse = (status) => {
+        if (!socket.destroyed) {
+            socket.end(`HTTP/1.1 ${status}\r\n\r\n`);
+        }
+    };
+    try {
+        upstream = request({ hostname: target.hostname, port: target.port, method: req.method, path: req.url, headers: req.headers });
+    }
+    catch {
+        refuse('502 Bad Gateway');
+        return;
+    }
+    upstream.on('upgrade', (reply, upgraded, upstreamHead) => {
+        upstreamSocket = upgraded;
+        track(upgraded);
+        upgraded.on('error', teardown);
+        upgraded.on('close', teardown);
+        if (socket.destroyed) {
+            upgraded.destroy();
+            return;
+        }
+        const lines = [`HTTP/1.1 ${String(reply.statusCode ?? 101)} ${reply.statusMessage ?? 'Switching Protocols'}`];
+        for (let i = 0; i < reply.rawHeaders.length; i += 2) {
+            lines.push(`${reply.rawHeaders[i] ?? ''}: ${reply.rawHeaders[i + 1] ?? ''}`);
+        }
+        socket.write(`${lines.join('\r\n')}\r\n\r\n`);
+        if (upstreamHead.length > 0) {
+            socket.write(upstreamHead);
+        }
+        if (head.length > 0) {
+            upgraded.write(head);
+        }
+        upgraded.pipe(socket).pipe(upgraded);
+    });
+    upstream.on('response', (reply) => {
+        reply.resume();
+        refuse(`${String(reply.statusCode ?? 502)} ${reply.statusMessage ?? ''}`);
+    });
+    upstream.on('error', () => {
+        refuse('502 Bad Gateway');
+    });
+    upstream.end();
+}
+/** Closes the cell and every connection it holds, upgraded ones included. */
+export async function closeCell(cell) {
+    await new Promise((done) => {
+        cell.close(() => {
+            done();
+        });
+        cell.closeAllConnections();
+        cell.destroyUpgrades();
+    });
+}
+/**
+ * The dev cell (cell resolution design 3): an origin of its own, as a deployed cell is, that answers each domain's
+ * `/<id>/ui/…` and `/<id>/api/…` by forwarding to the server that has it, with the path and `Host` unchanged and
+ * WebSocket upgrades included. The shell loads every domain from here, cross-origin, as it does from a deployed cell;
+ * the servers behind it answer CORS for the console's origin. Anything else is 404, and a `Host` that is not
+ * `localhost` or an IP address is 403 (`isAllowedHost`).
+ */
+export function createCellServer(options) {
+    const targetOf = (url) => {
+        const id = domainOf(url);
+        const origin = id === null ? undefined : options.targets().get(id);
+        return origin === undefined ? null : new URL(origin);
+    };
+    const server = createServer((req, res) => {
+        if (!isAllowedHost(req.headers.host)) {
+            refuseHost(res);
+            return;
+        }
+        const target = targetOf(req.url);
+        if (target === null) {
+            answer(res, 404, 'not found');
+            return;
+        }
+        forward(req, res, target, options.logger);
+    });
+    const upgraded = new Set();
+    const track = (socket) => {
+        upgraded.add(socket);
+        socket.once('close', () => {
+            upgraded.delete(socket);
+        });
+    };
+    server.on('upgrade', (req, socket, head) => {
+        track(socket);
+        // Node has removed its own listener by now; a reset while this socket is refused must not end the process.
+        socket.on('error', () => {
+            socket.destroy();
+        });
+        if (!isAllowedHost(req.headers.host)) {
+            refuseUpgradeHost(socket);
+            return;
+        }
+        const target = targetOf(req.url);
+        if (target === null) {
+            socket.end('HTTP/1.1 404 Not Found\r\n\r\n');
+            return;
+        }
+        forwardUpgrade(req, socket, head, target, track);
+    });
+    return Object.assign(server, {
+        destroyUpgrades: () => {
+            for (const socket of upgraded) {
+                socket.destroy();
+            }
+        },
+    });
+}

package/dist/cli.js

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import process from 'node:process';
-import { USAGE, parseTokenArgs, parseTtl } from './args.js';
+import { USAGE, parseServeArgs, parseTokenArgs, parseTtl } from './args.js';
+import { serveDevShell } from './serve.js';
 import { assertClaimsInput } from './devfile.js';
 import { DEFAULT_TTL_MS, loadOrCreateKey, mintToken } from './token.js';
 const defaultIo = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) };
@@ -42,6 +43,27 @@ function runToken(argv, io) {
     io.stdout(output);
     return 0;
 }
+/** Both `src/` and `dist/` sit one level below the package root, next to `platform/`. */
+const PLATFORM_DIR = resolve(import.meta.dirname, '../platform');
+async function runServe(argv, io) {
+    const args = parseServeArgs(argv);
+    if (args.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    if (args.shellDir === undefined) {
+        throw new Error('serve needs --shell-dir: the shell\'s devhost build');
+    }
+    const cwd = io.cwd ?? process.cwd();
+    const logger = { info: (msg) => io.stdout(`${msg}\n`), warn: (msg) => io.stderr(`${msg}\n`) };
+    const serving = await serveDevShell({
+        shellDir: resolve(cwd, args.shellDir), platformDir: PLATFORM_DIR, config: args.config, cwd, port: args.port,
+        cellPort: args.cellPort, keyDir: io.keyDir, logger,
+    });
+    io.stdout(`  shell  http://localhost:${String(serving.consolePort)}/  (the console)\n`);
+    io.stdout(`  cell   http://localhost:${String(serving.cellPort)}/  (every domain, as the shell loads them)\n`);
+    return 0;
+}
 export async function main(argv, io = defaultIo) {
     const [command, ...rest] = argv;
     try {
@@ -53,6 +75,8 @@ export async function main(argv, io = defaultIo) {
                 return 0;
             case 'token':
                 return runToken(rest, io);
+            case 'serve':
+                return await runServe(rest, io);
             default:
                 io.stderr(`unknown command "${command}"\n\n${USAGE}`);
                 return 2;

package/dist/devfile.d.ts

@@ -5,12 +5,29 @@ export declare const DEV_FILE = "shell.dev.json";
 export interface DevLab {
     designSystem?: string;
 }
+/** A domain the ui-shell dev server's cell forwards to, and the origin of the server that has it. */
+export interface CellDomain {
+    id: string;
+    /** Required for a domain the shell does not compile in; a compiled one keeps its own. */
+    nav?: DevDomain['nav'];
+    /** The domain's server: `http://127.0.0.1:<port>` for a port in the file, or the origin given. */
+    at: string;
+}
+/**
+ * Where the ui-shell dev server's cell finds the domains (cell resolution design 3): each listed one at its server, and
+ * every compiled domain not listed at the built-in MFE.
+ */
+export interface CellConfig {
+    domains: CellDomain[];
+}
 export interface DevFile {
-    profile?: string;
-    overrides?: {
-        [id: string]: string;
-    };
+    /**
+     * The MFE project's own domain, when the shell does not compile it in. An MFE project's dev server runs the built-in
+     * MFEs and its own, nothing else; any `devPort` is ignored.
+     */
     domains?: DevDomain[];
+    /** The ui-shell dev server only: where its cell finds each domain. */
+    cell?: CellConfig;
     idleTimeoutMs?: number;
     landing?: string;
     /**
@@ -25,11 +42,10 @@ export declare function assertClaimsInput(value: unknown, source: string): DevCl
 /** An explicit `--config` must exist; the default `shell.dev.json` is optional. */
 export declare function loadDevFile(path: string | undefined, cwd?: string): DevFile | null;
 export interface DevOverrides {
-    profile?: string;
     landing?: string;
-    overrides: {
-        [id: string]: string;
-    };
 }
-/** 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 declare function buildDevConfig(file: DevFile | null, args: DevOverrides, session: Session | undefined): DevConfig;