@heswell/vuu-portal 0.0.0-stage → 2.0.0

package/195.js

@@ -0,0 +1,448 @@
+import { ConfigFactory, EditSessionRpcHandler, ModuleFactory, Provider, TableDef, VUU_DEFAULT_COLUMNS, ViewPortDef, createConfiguredAuthProviders, createVuuServerApplication } from "@heswell/vuu-server";
+import { MODULE_ADMIN_RPC, executeModuleAdminRpc, managedModuleColumnValues, managedModulePermissionValues, validateModuleConfig } from "@heswell/module-admin";
+import node_fs from "node:fs";
+import node_path from "node:path";
+function moduleClientIdentifier(name) {
+    const kebab = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+    return kebab.startsWith("vuu-") ? kebab : `vuu-${kebab}`;
+}
+function createModuleRegistry(tableContainer, user) {
+    return {
+        modules: selectModules(readModules(tableContainer.getTable("modules")), readModulePermissions(tableContainer.getTable("modulePermissions")), user.authorizations)
+    };
+}
+function readModules(table) {
+    return table.rows.map((row)=>{
+        const name = stringValue(table, row, "name");
+        const parentModuleId = numberValue(table, row, "parentModuleId");
+        return {
+            clientIdentifier: moduleClientIdentifier(name),
+            id: numberValue(table, row, "id"),
+            parentModuleId,
+            accessRole: "",
+            name,
+            title: stringValue(table, row, "title"),
+            description: stringValue(table, row, "description"),
+            version: numberValue(table, row, "version"),
+            enabled: booleanValue(table, row, "enabled"),
+            navLocation: 0 === parentModuleId ? stringValue(table, row, "location") : "",
+            path: stringValue(table, row, "path"),
+            mfComponent: stringValue(table, row, "mfComponent"),
+            mfScope: stringValue(table, row, "mfScope"),
+            mfUrl: stringValue(table, row, "mfUrl"),
+            ...navIcon(table, row)
+        };
+    });
+}
+function navIcon(table, row) {
+    const navIconUrl = row[columnIndex(table, "navIconUrl")];
+    return "string" == typeof navIconUrl && navIconUrl ? {
+        navIconUrl
+    } : {};
+}
+function readModulePermissions(table) {
+    return table.rows.map((row)=>({
+            moduleId: numberValue(table, row, "module_id"),
+            role: stringValue(table, row, "role")
+        }));
+}
+function selectModules(modules, modulePermissions, authorizations) {
+    const moduleRoles = new Map();
+    const permittedModuleRoles = new Map();
+    const roles = new Set(authorizations);
+    modulePermissions.forEach(({ moduleId, role })=>{
+        moduleRoles.set(moduleId, role);
+        if (roles.has(role)) permittedModuleRoles.set(moduleId, role);
+    });
+    const latestByName = new Map();
+    modules.forEach((module)=>{
+        const accessRole = accessRoleForModule(module, moduleRoles, permittedModuleRoles);
+        if (!module.enabled || !accessRole) return;
+        const moduleWithAccess = {
+            ...module,
+            accessRole
+        };
+        const current = latestByName.get(module.name);
+        if (!current || module.version > current.version || module.version === current.version && module.id > current.id) latestByName.set(module.name, moduleWithAccess);
+    });
+    const permittedModules = [
+        ...latestByName.values()
+    ];
+    const permittedIds = new Set(permittedModules.map(({ id })=>id));
+    return permittedModules.filter(({ parentModuleId })=>0 === parentModuleId || permittedIds.has(parentModuleId)).map(({ parentModuleId: _parentModuleId, ...module })=>module).sort((left, right)=>left.name.localeCompare(right.name));
+}
+function accessRoleForModule(module, moduleRoles, permittedModuleRoles) {
+    const ownRole = permittedModuleRoles.get(module.id);
+    if (ownRole) return ownRole;
+    if (0 !== module.parentModuleId && !moduleRoles.has(module.id)) return permittedModuleRoles.get(module.parentModuleId) ?? "";
+    return "";
+}
+function stringValue(table, row, column) {
+    const value = row[columnIndex(table, column)];
+    if ("string" != typeof value) throw new Error(`Expected ${table.name}.${column} to be a string`);
+    return value;
+}
+function numberValue(table, row, column) {
+    const value = row[columnIndex(table, column)];
+    if ("number" != typeof value) throw new Error(`Expected ${table.name}.${column} to be a number`);
+    return value;
+}
+function booleanValue(table, row, column) {
+    const value = row[columnIndex(table, column)];
+    if ("boolean" != typeof value) throw new Error(`Expected ${table.name}.${column} to be a boolean`);
+    return value;
+}
+function columnIndex(table, column) {
+    const index = table.tableDef.columns.findIndex(({ name })=>name === column);
+    if (-1 === index) throw new Error(`Table ${table.name} does not contain ${column}`);
+    return index;
+}
+const modulesTable = TableDef({
+    columns: [
+        {
+            name: "id",
+            dataType: "int"
+        },
+        {
+            name: "parentModuleId",
+            dataType: "int"
+        },
+        {
+            name: "name",
+            dataType: "string"
+        },
+        {
+            name: "title",
+            dataType: "string"
+        },
+        {
+            name: "description",
+            dataType: "string"
+        },
+        {
+            name: "version",
+            dataType: "int"
+        },
+        {
+            name: "enabled",
+            dataType: "boolean"
+        },
+        {
+            name: "location",
+            dataType: "string"
+        },
+        {
+            name: "path",
+            dataType: "string"
+        },
+        {
+            name: "mfComponent",
+            dataType: "string"
+        },
+        {
+            name: "mfScope",
+            dataType: "string"
+        },
+        {
+            name: "mfUrl",
+            dataType: "string"
+        },
+        {
+            name: "navIconUrl",
+            dataType: "string"
+        },
+        ...VUU_DEFAULT_COLUMNS
+    ],
+    keyField: "id",
+    name: "modules"
+});
+const modulePermissionsTable = TableDef({
+    columns: [
+        {
+            name: "id",
+            dataType: "int"
+        },
+        {
+            name: "module_id",
+            dataType: "int"
+        },
+        {
+            name: "role",
+            dataType: "string"
+        },
+        ...VUU_DEFAULT_COLUMNS
+    ],
+    keyField: "id",
+    name: "modulePermissions"
+});
+class ModuleDiscoveryProvider extends Provider {
+    rows;
+    constructor(table, rows){
+        super(table), this.rows = rows;
+    }
+    async load() {
+        for (const row of this.rows)this.table.insert(row, false);
+    }
+}
+const success = (data)=>({
+        type: "SUCCESS_RESULT",
+        data
+    });
+const failure = (errorMessage)=>({
+        type: "ERROR_RESULT",
+        errorMessage
+    });
+const toErrorMessage = (error)=>error instanceof Error ? error.message : String(error);
+const DEFAULT_MODULE_ADMIN_ROLE = "module-admin-access";
+class ModuleAdminService extends EditSessionRpcHandler {
+    state;
+    adminRole;
+    now;
+    constructor(tableContainer, state, { adminRole = DEFAULT_MODULE_ADMIN_ROLE, now = Date.now } = {}){
+        super(tableContainer), this.state = state;
+        this.adminRole = adminRole;
+        this.now = now;
+        this.registerRpc(MODULE_ADMIN_RPC.createModule, this.handleModuleAdminRpc("createModule"));
+        this.registerRpc(MODULE_ADMIN_RPC.updateModule, this.handleModuleAdminRpc("updateModule"));
+        this.registerRpc(MODULE_ADMIN_RPC.setModuleEnabled, this.handleModuleAdminRpc("setModuleEnabled"));
+        this.registerRpc(MODULE_ADMIN_RPC.deleteModule, this.handleModuleAdminRpc("deleteModule"));
+    }
+    handleModuleAdminRpc(rpcName) {
+        return async ({ ctx, namedParams })=>{
+            if (!ctx?.user?.authorizations?.includes(this.adminRole)) return failure(`Administering modules requires the ${this.adminRole} role`);
+            try {
+                const { modules, result } = executeModuleAdminRpc(this.state.modules, rpcName, namedParams, this.now);
+                this.state.replaceAndSave(modules);
+                this.syncTables(modules);
+                return success(result);
+            } catch (error) {
+                return failure(toErrorMessage(error));
+            }
+        };
+    }
+    syncTables(modules) {
+        syncTable(this.tableContainer.getTable("modules"), modules.map(managedModuleColumnValues));
+        syncTable(this.tableContainer.getTable("modulePermissions"), managedModulePermissionValues(modules));
+    }
+}
+function syncTable(table, values) {
+    const expectedKeys = new Set(values.map((row)=>String(row[table.schema.key])));
+    for (const row of [
+        ...table.rows
+    ]){
+        const key = String(row[table.indexOfKeyField]);
+        if (!expectedKeys.has(key)) table.delete(key);
+    }
+    for (const rowValues of values){
+        const row = table.tableDef.columns.map(({ name })=>rowValues[name] ?? "");
+        const key = String(row[table.indexOfKeyField]);
+        const existing = table.getRowAtKey(key, false);
+        if (existing) {
+            row[table.columnMap.vuuCreatedTimestamp] = existing[table.columnMap.vuuCreatedTimestamp];
+            table.update(table.rowIndexAtKey(key), row);
+        } else table.insert(row);
+    }
+}
+const yaml = ()=>{
+    if ("u" < typeof Bun || !Bun.YAML) throw new Error("@heswell/vuu-portal module files require the Bun runtime");
+    return Bun.YAML;
+};
+class InMemoryModuleStore {
+    modules;
+    constructor(modules = []){
+        this.modules = modules;
+    }
+    load() {
+        return cloneModules(this.modules);
+    }
+    save(modules) {
+        this.modules = cloneModules(modules);
+    }
+}
+class ModuleState {
+    store;
+    #modules;
+    constructor(store, modules){
+        this.store = store;
+        this.#modules = cloneModules(modules);
+    }
+    get modules() {
+        return cloneModules(this.#modules);
+    }
+    replaceAndSave(modules) {
+        const next = cloneModules(modules);
+        this.store.save(next);
+        this.#modules = next;
+    }
+}
+class YamlModuleStore {
+    filePath;
+    seedModules;
+    constructor(filePath, seedModules){
+        this.filePath = filePath;
+        this.seedModules = seedModules;
+    }
+    load() {
+        if (!node_fs.existsSync(this.filePath)) {
+            const seeded = cloneModules(this.seedModules());
+            assertValidManagedModules(seeded, this.filePath);
+            this.save(seeded);
+            return seeded;
+        }
+        const modules = readModulesFile(this.filePath).map((value, index)=>parseManagedModule(value, index));
+        assertValidManagedModules(modules, this.filePath);
+        return modules;
+    }
+    save(modules) {
+        const directory = node_path.dirname(this.filePath);
+        node_fs.mkdirSync(directory, {
+            recursive: true
+        });
+        const tempPath = node_path.join(directory, `.${node_path.basename(this.filePath)}.${process.pid}.${Date.now()}.tmp`);
+        const contents = yaml().stringify({
+            modules: cloneModules(modules)
+        }, null, 2);
+        try {
+            node_fs.writeFileSync(tempPath, contents, "utf8");
+            node_fs.renameSync(tempPath, this.filePath);
+        } catch (error) {
+            try {
+                if (node_fs.existsSync(tempPath)) node_fs.unlinkSync(tempPath);
+            } catch  {}
+            throw error;
+        }
+    }
+}
+function createModuleState(store) {
+    return new ModuleState(store, store.load());
+}
+function loadDefaultModules(filePath, timestamp) {
+    const modules = readModulesFile(filePath).map((value, index)=>parseManagedModule(isRecord(value) ? {
+            ...value,
+            created: timestamp,
+            updated: timestamp
+        } : value, index));
+    assertValidManagedModules(modules, filePath);
+    return modules;
+}
+function readModulesFile(filePath) {
+    const parsed = yaml().parse(node_fs.readFileSync(filePath, "utf8"));
+    if (!isRecord(parsed) || !Array.isArray(parsed.modules)) throw new Error(`Modules file '${filePath}' must contain a 'modules' list`);
+    return parsed.modules;
+}
+function cloneModules(modules) {
+    return modules.map((module)=>({
+            ...module
+        }));
+}
+const managedModuleKeys = [
+    "id",
+    "version",
+    "created",
+    "updated",
+    "parentModuleId",
+    "name",
+    "title",
+    "description",
+    "enabled",
+    "location",
+    "path",
+    "mfComponent",
+    "mfScope",
+    "mfUrl",
+    "navIconUrl",
+    "accessRole"
+];
+const retiredModuleKeys = [
+    "vuuConnectionId",
+    "vuuWebsocketUrl",
+    "vuuRestUrl"
+];
+function parseManagedModule(value, index) {
+    if (!isRecord(value)) throw new Error(`Modules file entry ${index} must be an object`);
+    for (const key of Object.keys(value))if (!managedModuleKeys.includes(key) && !retiredModuleKeys.includes(key)) throw new Error(`Modules file entry ${index} contains unknown field '${key}'`);
+    const module = {};
+    for (const key of managedModuleKeys){
+        const fieldValue = value[key];
+        if (void 0 === fieldValue) throw new Error(`Modules file entry ${index} is missing '${key}'`);
+        const expected = [
+            "id",
+            "version",
+            "created",
+            "updated",
+            "parentModuleId"
+        ].includes(key) ? "number" : "enabled" === key ? "boolean" : "string";
+        if (typeof fieldValue !== expected) throw new Error(`Modules file entry ${index} field '${key}' must be a ${expected}`);
+        if ("number" === expected && !Number.isInteger(fieldValue)) throw new Error(`Modules file entry ${index} field '${key}' must be an integer`);
+        module[key] = fieldValue;
+    }
+    return module;
+}
+function assertValidManagedModules(modules, filePath) {
+    const ids = new Set();
+    modules.forEach((module, index)=>{
+        if (ids.has(module.id)) throw new Error(`Modules file '${filePath}' contains duplicate id ${module.id}`);
+        ids.add(module.id);
+        const errors = validateModuleConfig(module, modules, module.id);
+        const message = formatValidationErrors(errors);
+        if (message) throw new Error(`Modules file '${filePath}' entry ${index} is invalid: ${message}`);
+    });
+}
+function formatValidationErrors(errors) {
+    return Object.entries(errors).filter(([, message])=>message).map(([field, message])=>`${field}: ${message}`).join("; ");
+}
+function isRecord(value) {
+    return "object" == typeof value && null !== value && !Array.isArray(value);
+}
+function loadModuleState(config) {
+    const filePath = config.getPath("vuu.portal.modulesFile", "modules.yaml");
+    const defaultsPath = config.getPath("vuu.portal.defaultModulesFile", "default-modules.yaml");
+    return createModuleState(new YamlModuleStore(filePath, ()=>loadDefaultModules(defaultsPath, Date.now())));
+}
+function loadModuleAdminRole(config) {
+    const role = config.getString("vuu.portal.moduleAdminRole", DEFAULT_MODULE_ADMIN_ROLE).trim();
+    if (!role) throw new Error("vuu.portal.moduleAdminRole must not be empty");
+    return role;
+}
+const ModuleDiscoveryModule = (state, { adminRole = DEFAULT_MODULE_ADMIN_ROLE } = {})=>{
+    const modules = state.modules;
+    const moduleRows = modules.map((module)=>valuesToRow(modulesTable, managedModuleColumnValues(module)));
+    const permissionRows = managedModulePermissionValues(modules).map((values)=>valuesToRow(modulePermissionsTable, values));
+    let service;
+    const getService = (tableContainer)=>service ??= new ModuleAdminService(tableContainer, state, {
+            adminRole
+        });
+    return ModuleFactory.withNameSpace("MODULE_DISCOVERY").addTable(modulesTable, (table)=>new ModuleDiscoveryProvider(table, moduleRows), (table, _provider, _providerContainer, tableContainer)=>ViewPortDef(columnsFor(table), getService(tableContainer))).addTable(modulePermissionsTable, (table)=>new ModuleDiscoveryProvider(table, permissionRows), (table, _provider, _providerContainer, tableContainer)=>ViewPortDef(columnsFor(table), getService(tableContainer))).asModule();
+};
+function columnsFor(table) {
+    return table.schema.columns.map(({ name, serverDataType: dataType }, index)=>({
+            name,
+            dataType,
+            index
+        }));
+}
+function valuesToRow(table, values) {
+    return table.columns.map(({ name })=>values[name] ?? "");
+}
+const PORTAL_DEFAULT_HTTPS_PORT = 8443;
+const PORTAL_DEFAULT_WEBSOCKET_PATH = "/websocket-portal";
+const PORTAL_DEFAULT_WEBSOCKET_PORT = 8091;
+function createPortalApplication({ config, configFile } = {}) {
+    const portalConfig = config ?? ConfigFactory.load(configFile);
+    return createVuuServerApplication({
+        authProviders: createConfiguredAuthProviders(portalConfig),
+        config: portalConfig,
+        defaultHttpsPort: PORTAL_DEFAULT_HTTPS_PORT,
+        defaultWebSocketPath: PORTAL_DEFAULT_WEBSOCKET_PATH,
+        defaultWebSocketPort: PORTAL_DEFAULT_WEBSOCKET_PORT,
+        loginSuccessProvider: (user, tableContainer)=>({
+                moduleRegistry: createModuleRegistry(tableContainer, user)
+            }),
+        modules: [
+            ModuleDiscoveryModule(loadModuleState(portalConfig), {
+                adminRole: loadModuleAdminRole(portalConfig)
+            })
+        ]
+    });
+}
+export { DEFAULT_MODULE_ADMIN_ROLE, InMemoryModuleStore, ModuleDiscoveryModule, ModuleState, PORTAL_DEFAULT_WEBSOCKET_PATH, YamlModuleStore, createModuleRegistry, createModuleState, createPortalApplication, loadDefaultModules, loadModuleAdminRole, loadModuleState, moduleClientIdentifier };

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @heswell/vuu-portal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vuu portal server: a [`@heswell/vuu-server`](../vuu-server) application that
+hosts the `MODULE_DISCOVERY` module and returns each user's module registry in
+the login response. Requires the [Bun](https://bun.sh) runtime to run the
+server. The library exports can be imported under Node.js too.
+
+```sh
+npm install @heswell/vuu-portal
+# TypeScript consumers: the vuu-server declarations reference Bun types
+npm install -D @types/bun
+```
+
+## Entry points
+
+| Import / command | Purpose |
+| --- | --- |
+| `@heswell/vuu-portal` | Library API. Importing it has no side effects. |
+| `@heswell/vuu-portal/main` | `main(options?)`: creates and starts the portal. Importing it has no side effects. |
+| `vuu-portal` bin | Starts the portal from a shell. |
+
+```ts
+import {
+  createModuleRegistry,
+  createPortalApplication,
+  loadDefaultModules,
+  loadModuleAdminRole,
+  loadModuleState,
+  ModuleDiscoveryModule,
+} from "@heswell/vuu-portal";
+```
+
+Root exports:
+
+- `createPortalApplication({ config?, configFile? })` creates the portal
+  application without starting it.
+- `createModuleRegistry` and `moduleClientIdentifier`.
+- `ModuleDiscoveryModule`, `loadModuleState`, `loadModuleAdminRole`.
+- Module catalogue stores: `ModuleState`, `createModuleState`,
+  `YamlModuleStore`, `InMemoryModuleStore`, `loadDefaultModules` and the
+  `ModuleStore` type.
+- `DEFAULT_MODULE_ADMIN_ROLE`, plus the `PORTAL_DEFAULT_*` fallback ports and
+  path.
+
+## Starting the portal
+
+Everything is configured in `application.conf`. Point the portal at your own
+conf and run the stock entry unchanged:
+
+```sh
+# bin
+bunx vuu-portal --config ./path/to/application.conf
+VUU_CONFIG_FILE=./path/to/application.conf bunx vuu-portal
+
+# from code
+import { main } from "@heswell/vuu-portal/main";
+await main({ configFile: "./path/to/application.conf" });
+```
+
+The conf file is located in this order:
+
+1. `--config <path>` (bin) or `main({ configFile })`. Relative paths resolve
+   against the current directory.
+2. `$VUU_CONFIG_FILE`.
+3. `$VUU_APP`, which selects `packages/$VUU_APP/application.conf` under the
+   current directory.
+4. `./application.conf`.
+
+In this repository, `npm run start:portal` starts it with
+`VUU_APP=vuu-portal`, which uses [`application.conf`](./application.conf).
+
+### Settings
+
+Any setting can be overridden from the environment with a HOCON-style
+`${?VAR}` line in the conf, and the portal's own
+[`application.conf`](./application.conf) already does this for the ports,
+websocket path, auth mode, CORS origin, Keycloak URL and realm, and module
+files (`VUU_HTTPS_PORT`, `VUU_WEBSOCKET_PORT`, `VUU_WEBSOCKET_PATH`,
+`VUU_AUTH_MODE`, `VUU_CORS_ALLOWED_ORIGIN`, `VUU_KEYCLOAK_URL`,
+`VUU_KEYCLOAK_REALM`, `VUU_PORTAL_MODULES_FILE`,
+`VUU_PORTAL_DEFAULT_MODULES_FILE`). See the
+[`@heswell/service-utils` README](../service-utils/README.md#environment-variable-substitution)
+for the syntax.
+
+| Key | Fallback when not set |
+| --- | --- |
+| `vuu.https.port` | `8443` |
+| `vuu.websocket.port` | `8091` |
+| `vuu.websocket.path` | `/websocket-portal` |
+| `vuu.ssl`, `vuu.certPath`, `vuu.keyPath` | SSL disabled |
+| `vuu.auth.*`, `vuu.keycloak.*` | See [`@heswell/vuu-server`](../vuu-server/README.md) |
+| `vuu.portal.defaultModulesFile` | `default-modules.yaml` |
+| `vuu.portal.modulesFile` | `modules.yaml` |
+| `vuu.portal.moduleAdminRole` | `module-admin-access` |
+
+### Module catalogue
+
+The portal's modules are defined in YAML, not in code. Relative file paths
+are resolved against the directory that contains `application.conf`;
+absolute paths and `~/` paths are also accepted.
+
+- `vuu.portal.modulesFile` is the runtime state, edited through the module
+  admin. If it does not exist, it is created from the default modules file on
+  start.
+- `vuu.portal.defaultModulesFile` is the seed catalogue. See
+  [`default-modules.yaml`](./default-modules.yaml) for the format.

package/bin.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+import { main } from "./main.js";
+const USAGE = `Usage: vuu-portal [--config <path/to/application.conf>]
+
+Starts the Vuu portal server. All settings (ports, websocket path, auth,
+module catalogue files, module admin role) come from application.conf.
+
+Without --config the conf is located via $VUU_CONFIG_FILE, then $VUU_APP
+(packages/<app>/application.conf), then ./application.conf.`;
+const parseConfigFile = (args)=>{
+    let configFile;
+    for(let index = 0; index < args.length; index++){
+        const arg = args[index];
+        if ("--help" === arg || "-h" === arg) {
+            console.log(USAGE);
+            process.exit(0);
+        } else if ("--config" === arg || "-c" === arg) {
+            configFile = args[++index];
+            if (!configFile) throw new Error(`${arg} requires a path\n\n${USAGE}`);
+        } else if (arg.startsWith("--config=")) configFile = arg.slice(9);
+        else throw new Error(`Unknown argument '${arg}'\n\n${USAGE}`);
+    }
+    return configFile;
+};
+await main({
+    configFile: parseConfigFile(process.argv.slice(2))
+});

package/index.js

@@ -0,0 +1,4 @@
+var src_PORTAL_DEFAULT_HTTPS_PORT = 8443;
+var src_PORTAL_DEFAULT_WEBSOCKET_PORT = 8091;
+export { DEFAULT_MODULE_ADMIN_ROLE, InMemoryModuleStore, ModuleDiscoveryModule, ModuleState, PORTAL_DEFAULT_WEBSOCKET_PATH, YamlModuleStore, createModuleRegistry, createModuleState, createPortalApplication, loadDefaultModules, loadModuleAdminRole, loadModuleState, moduleClientIdentifier } from "./195.js";
+export { src_PORTAL_DEFAULT_HTTPS_PORT as PORTAL_DEFAULT_HTTPS_PORT, src_PORTAL_DEFAULT_WEBSOCKET_PORT as PORTAL_DEFAULT_WEBSOCKET_PORT };

package/main.js

@@ -0,0 +1,9 @@
+import { createPortalApplication } from "./195.js";
+async function main(options) {
+    const application = createPortalApplication(options);
+    await application.start();
+    return application;
+}
+const src_main = main;
+export default src_main;
+export { main };

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@heswell/vuu-portal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "VUU portal server with remote module discovery",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./index.js"
+    },
+    "./main": {
+      "types": "./src/main.d.ts",
+      "import": "./main.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./bin.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "heswell",
+  "license": "MIT",
+  "dependencies": {
+    "@heswell/module-admin": "2.0.1",
+    "@heswell/vuu-server": "3.1.0",
+    "@heswell/vuu-table": "1.0.1"
+  },
+  "peerDependencies": {
+    "@vuu-ui/vuu-protocol-types": "4.0.0-alpha.20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heswell/vuu-websocket.git",
+    "directory": "packages/vuu-portal"
+  },
+  "typesVersions": {
+    "*": {
+      "main": [
+        "./src/main.d.ts"
+      ]
+    }
+  },
+  "bin": {
+    "vuu-portal": "bin.js"
+  },
+  "files": [
+    "*.js",
+    "src/**/*.d.ts",
+    "README.md"
+  ]
+}

package/src/ModuleRegistry.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleRegistry, TableContainer, VuuUser } from "@heswell/vuu-server";
+/**
+ * Derives a module's own client identifier from its name, e.g.
+ * `userAdmin` -> `vuu-user-admin`. The UI keys each module's saved state by
+ * this value, so it must be unique per module.
+ */
+export declare function moduleClientIdentifier(name: string): string;
+export declare function createModuleRegistry(tableContainer: TableContainer, user: VuuUser): ModuleRegistry;

package/src/PortalApplication.d.ts

@@ -0,0 +1,21 @@
+import { type Config, type VuuServerApplication } from "@heswell/vuu-server";
+export declare const PORTAL_DEFAULT_HTTPS_PORT = 8443;
+export declare const PORTAL_DEFAULT_WEBSOCKET_PATH = "/websocket-portal";
+export declare const PORTAL_DEFAULT_WEBSOCKET_PORT = 8091;
+export type PortalApplicationOptions = {
+    /** An already loaded config. Takes precedence over `configFile`. */
+    config?: Config;
+    /**
+     * Path to the portal's application.conf, resolved against the current
+     * directory. Defaults to ConfigFactory's lookup: $VUU_CONFIG_FILE, then
+     * $VUU_APP, then ./application.conf.
+     */
+    configFile?: string;
+};
+/**
+ * Creates (but does not start) the portal server, configured entirely by
+ * application.conf: ports, websocket path, auth, the module catalogue files
+ * (vuu.portal.modulesFile / vuu.portal.defaultModulesFile, resolved relative
+ * to the conf file) and the module admin role (vuu.portal.moduleAdminRole).
+ */
+export declare function createPortalApplication({ config, configFile, }?: PortalApplicationOptions): VuuServerApplication;

package/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export { createModuleRegistry, moduleClientIdentifier, } from "./ModuleRegistry.js";
+export { loadModuleAdminRole, loadModuleState, ModuleDiscoveryModule, ModuleState, } from "./modules/ModuleDiscovery/ModuleDiscoveryModule.js";
+export { createModuleState, InMemoryModuleStore, loadDefaultModules, type ModuleStore, YamlModuleStore, } from "./modules/ModuleDiscovery/ModuleStore.js";
+export { DEFAULT_MODULE_ADMIN_ROLE } from "./modules/ModuleDiscovery/ModuleAdminService.js";
+export { createPortalApplication, PORTAL_DEFAULT_HTTPS_PORT, PORTAL_DEFAULT_WEBSOCKET_PATH, PORTAL_DEFAULT_WEBSOCKET_PORT, type PortalApplicationOptions, } from "./PortalApplication.js";

package/src/main.d.ts

@@ -0,0 +1,8 @@
+import { type PortalApplicationOptions } from "./PortalApplication.js";
+/**
+ * Creates and starts the portal application from application.conf (see
+ * createPortalApplication). Importing this module has no side effects; use
+ * the `vuu-portal` bin to start the portal from a shell.
+ */
+export declare function main(options?: PortalApplicationOptions): Promise<import("@heswell/vuu-server").VuuServerApplication>;
+export default main;

package/src/modules/ModuleDiscovery/ModuleAdminService.d.ts

@@ -0,0 +1,16 @@
+import { EditSessionRpcHandler, type TableContainer } from "@heswell/vuu-server";
+import type { ModuleState } from "./ModuleStore.js";
+export declare const DEFAULT_MODULE_ADMIN_ROLE = "module-admin-access";
+export interface ModuleAdminServiceOptions {
+    /** Role a user must hold to create, update, enable/disable or delete modules. */
+    adminRole?: string;
+    now?: () => number;
+}
+export declare class ModuleAdminService extends EditSessionRpcHandler {
+    private readonly state;
+    private readonly adminRole;
+    private readonly now;
+    constructor(tableContainer: TableContainer, state: ModuleState, { adminRole, now }?: ModuleAdminServiceOptions);
+    private handleModuleAdminRpc;
+    private syncTables;
+}

package/src/modules/ModuleDiscovery/ModuleDiscoveryModule.d.ts

@@ -0,0 +1,8 @@
+import type { Config } from "@heswell/vuu-server";
+import { ModuleState } from "./ModuleStore.js";
+export { InMemoryModuleStore, ModuleState, YamlModuleStore, createModuleState, loadDefaultModules, } from "./ModuleStore.js";
+export declare function loadModuleState(config: Pick<Config, "getPath">): ModuleState;
+export declare function loadModuleAdminRole(config: Pick<Config, "getString">): string;
+export declare const ModuleDiscoveryModule: (state: ModuleState, { adminRole }?: {
+    adminRole?: string;
+}) => import("@heswell/vuu-server").Module;

package/src/modules/ModuleDiscovery/ModuleDiscoveryProvider.d.ts

@@ -0,0 +1,7 @@
+import { Table } from "@heswell/vuu-table";
+import { Provider } from "@heswell/vuu-server";
+export declare class ModuleDiscoveryProvider extends Provider {
+    private readonly rows;
+    constructor(table: Table, rows: Array<Array<string | number | boolean>>);
+    load(): Promise<void>;
+}

package/src/modules/ModuleDiscovery/ModuleDiscoveryService.d.ts

@@ -0,0 +1 @@
+export { ModuleAdminService as ModuleDiscoveryService } from "./ModuleAdminService.js";

package/src/modules/ModuleDiscovery/ModuleDiscoveryTableDefs.d.ts

@@ -0,0 +1,3 @@
+import { TableDef } from "@heswell/vuu-server";
+export declare const modulesTable: TableDef;
+export declare const modulePermissionsTable: TableDef;

package/src/modules/ModuleDiscovery/ModuleStore.d.ts

@@ -0,0 +1,66 @@
+import { type ManagedModule } from "@heswell/module-admin";
+export interface ModuleStore {
+    load(): ManagedModule[];
+    save(modules: readonly ManagedModule[]): void;
+}
+export declare class InMemoryModuleStore implements ModuleStore {
+    private modules;
+    constructor(modules?: readonly ManagedModule[]);
+    load(): {
+        parentModuleId: number;
+        name: string;
+        title: string;
+        description: string;
+        enabled: boolean;
+        location: string;
+        path: string;
+        mfComponent: string;
+        mfScope: string;
+        mfUrl: string;
+        navIconUrl: string;
+        accessRole: string;
+        id: number;
+        version: number;
+        created: number;
+        updated: number;
+    }[];
+    save(modules: readonly ManagedModule[]): void;
+}
+export declare class ModuleState {
+    #private;
+    private readonly store;
+    constructor(store: ModuleStore, modules: readonly ManagedModule[]);
+    get modules(): {
+        parentModuleId: number;
+        name: string;
+        title: string;
+        description: string;
+        enabled: boolean;
+        location: string;
+        path: string;
+        mfComponent: string;
+        mfScope: string;
+        mfUrl: string;
+        navIconUrl: string;
+        accessRole: string;
+        id: number;
+        version: number;
+        created: number;
+        updated: number;
+    }[];
+    replaceAndSave(modules: readonly ManagedModule[]): void;
+}
+export declare class YamlModuleStore implements ModuleStore {
+    private readonly filePath;
+    private readonly seedModules;
+    constructor(filePath: string, seedModules: () => readonly ManagedModule[]);
+    load(): ManagedModule[];
+    save(modules: readonly ManagedModule[]): void;
+}
+export declare function createModuleState(store: ModuleStore): ModuleState;
+/**
+ * Reads the default module catalog used to seed `modules.yaml`. Entries have
+ * the same fields as `modules.yaml`, except `created` and `updated`, which are
+ * set to `timestamp`.
+ */
+export declare function loadDefaultModules(filePath: string, timestamp: number): ManagedModule[];