Zayin/Ekklesia
3
0
Fork 0
Code Issues 6 Pull Requests 1 Actions Packages Projects Releases 9 Wiki Activity

Add the module navigation contract: manifest v9, module routes, return-to-origin

Browse Source 
Stage 1 PR 7 (ADR 0063). A module becomes a first-class part of the Dashboard.

- Manifest v9 = v8 plus optional `navigation`: a Lucide icon from the curated
  MODULE_NAVIGATION_ICONS set, and up to 12 primary pages (stable id, safe
  label, kebab-case path relative to the module root; no traversal, schemes,
  queries, duplicates, or nesting). Validated before activation.
- Version 8 stays accepted beside version 9, each read strictly as itself
  (discriminated union); no released manifest is rewritten. The template
  moves to v9; the released Signage 0.1.5 manifest is a test fixture.
- Real module routes: /<id> is the landing view, /<id>/<page> a declared
  page, anything beneath a page a module-owned detail route; anything else
  is not-found and mounts nothing. api/assets/display are never pages.
- Sidebar: declared icons, pages nested under an open module, one
  aria-current, collapsed and drawer behaviour; v8 modules unchanged.
- module-ui-sdk: ModuleUiHostContext.navigation (location, subscribe,
  navigate, link, settings), refusing anything outside the module's routes;
  undefined on the display host. Mount ABI unchanged.
- Return-to-origin: one `?return=` carrier on Settings URLs, validated by
  parseReturnTarget and against running modules' declared routes; Settings
  Back returns to exactly the originating module page, across refreshes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
ekklesia
2026-10-15 08:21:50 -05:00
co-authored by Claude Opus 5.5
parent 7447381c8f
commit 4671622b9d
69 changed files with 4221 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/api/src/dashboard-routes.ts
+31 -5
View File
@@ -21,7 +21,11 @@ import {
requireTrustedOrigin,
} from "./authorization-middleware.js";
import { CORE_MUTATION_MAX_BODY_BYTES, platformBodyLimit } from "./body-limits.js";
import { describeMountableModules, type HostModuleUiDescriptor } from "./module-ui-inventory.js";
import {
describeMountableModules,
type HostModuleUiDescriptor,
type MountableModuleDescription,
} from "./module-ui-inventory.js";
export const DASHBOARD_NAVIGATION_PATH = "/api/v1/dashboard/navigation";
const DASHBOARD_GROUPS_PATH = `${DASHBOARD_NAVIGATION_PATH}/groups`;
@@ -41,6 +45,20 @@ const DASHBOARD_PLACEMENTS_PATH = `${DASHBOARD_NAVIGATION_PATH}/placements`;
export interface DashboardNavigationModuleView {
readonly name: string;
readonly module: HostModuleUiDescriptor;
/**
* What the module declares about its own pages (manifest v9, ADR 0063): the Lucide icon the
* Dashboard draws it with (`null` for the generic one) and its primary pages, in declared order —
* empty for a single-page module, which every manifest v8 module is. The module's identity, never
* its placement: where it sits in the sidebar stays the administrator's (ADR 0027).
*/
readonly navigation: {
readonly icon: string | null;
readonly pages: readonly {
readonly id: string;
readonly label: string;
readonly path: string;
}[];
};
}
export interface DashboardNavigationGroupView {
@@ -203,10 +221,18 @@ export function createDashboardRoutes(options: CreateDashboardRoutesOptions): Ho
configuration,
descriptors.map((entry) => ({ id: entry.descriptor.id, ...entry })),
);
const present = (entry: {
readonly descriptor: HostModuleUiDescriptor;
readonly name: string;
}): DashboardNavigationModuleView => ({ module: entry.descriptor, name: entry.name });
const present = (entry: MountableModuleDescription): DashboardNavigationModuleView => ({
module: entry.descriptor,
name: entry.name,
navigation: {
icon: entry.navigation.icon ?? null,
pages: entry.navigation.pages.map((page) => ({
id: page.id,
label: page.label,
path: page.path,
})),
},
});
return c.json(
{
groups: view.groups.map((group) => ({
apps/api/src/module-ui-inventory.ts
+10 -1
View File
@@ -1,4 +1,8 @@
import type { EkklesiaPrincipal, PermissionDeclaration } from "@ekklesia/contracts";
import type {
EkklesiaPrincipal,
ModuleNavigationDeclaration,
PermissionDeclaration,
} from "@ekklesia/contracts";
import { CORE_MODULES_UI_READ } from "@ekklesia/core/authorization";
import type {
ModuleUiPublicationRegistry,
@@ -196,6 +200,10 @@ export interface MountableModuleDescription {
* Dashboard owns (ADR 0027). Deliberately absent from `HostModuleUiDescriptor`, so the
* host-neutral contract a standalone host consumes stays free of presentation concerns. */
readonly name: string;
/** The module's own declared icon and primary pages (manifest v9, ADR 0063); empty for one that
* declares none. Presentation identity like `name`, and kept beside the descriptor for the same
* reason. */
readonly navigation: ModuleNavigationDeclaration;
}
/**
@@ -216,6 +224,7 @@ export async function describeMountableModules(
registry.list().map(async (published) => ({
descriptor: await describeModule(evaluator, principal, published, registry),
name: published.name,
navigation: published.navigation,
})),
);
}
apps/api/tests/dashboard-host-routes.test.ts
+22 -1
View File
@@ -43,7 +43,13 @@ import {
DashboardHostConfigurationError,
createDashboardHostRoutes,
} from "../src/dashboard-host-routes.js";
import { DASHBOARD_PLATFORM_PAGES, SETTINGS_SECTIONS } from "@ekklesia/shell/dashboard-routes";
import { MODULE_NAVIGATION_ICONS } from "@ekklesia/contracts";
import {
DASHBOARD_PLATFORM_PAGES,
HOST_NAMESPACES,
SETTINGS_SECTIONS,
} from "@ekklesia/shell/dashboard-routes";
import { DASHBOARD_MODULE_ICON_NAMES } from "@ekklesia/shell/module-icons";
import {
MODULE_DISPLAY_DESCRIPTOR_PREFIX,
MODULE_DISPLAY_PAGE_PREFIX,
@@ -417,6 +423,14 @@ describe("the platform's reserved top-level names (ADR 0057)", () => {
}
});
it("are exactly the Dashboard's platform pages plus the host namespaces it never treats as pages (ADR 0063)", () => {
// With module routes nested beneath `/<module-id>/`, the shell must know every other top-level
// name: `/api/v1/principal` must never read as the route `v1/principal` of a module called `api`.
expect([...DASHBOARD_PLATFORM_PAGES, ...HOST_NAMESPACES].sort()).toEqual([
...RESERVED_TOP_LEVEL_NAMES,
]);
});
it("include exactly the Settings sections the shell interprets, so /settings/<module-id> never collides (ADR 0061)", () => {
expect([...SETTINGS_SECTIONS].sort()).toEqual([...RESERVED_SETTINGS_NAMES]);
for (const section of SETTINGS_SECTIONS) {
@@ -630,3 +644,10 @@ describe("Dashboard host boundaries", () => {
}
});
});
describe("module navigation icons (ADR 0063)", () => {
it("are the same set in the manifest contract and in the Dashboard that draws them", () => {
// The platform cannot accept an icon the Dashboard cannot draw, nor draw one it would refuse.
expect([...DASHBOARD_MODULE_ICON_NAMES]).toEqual([...MODULE_NAVIGATION_ICONS]);
});
});
apps/api/tests/dashboard-routes.test.ts
+74 -2
View File
@@ -55,6 +55,8 @@ interface ModuleFixture {
readonly id: string;
readonly name: string;
readonly withUi?: boolean;
/** Present, the fixture is a manifest v9 module declaring this navigation (ADR 0063). */
readonly navigation?: unknown;
}
async function createModule(modulesDirectory: string, fixture: ModuleFixture): Promise<void> {
@@ -78,8 +80,9 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
...(fixture.withUi === false ? {} : { ui: "./dist/ui/index.js" }),
},
id: fixture.id,
manifestVersion: 8,
manifestVersion: fixture.navigation === undefined ? 8 : 9,
name: fixture.name,
...(fixture.navigation === undefined ? {} : { navigation: fixture.navigation }),
version: "1.0.0",
}),
);
@@ -170,6 +173,14 @@ function signedIn(): EkklesiaPrincipal {
interface NavigationEntry {
readonly name: string;
readonly navigation: {
readonly icon: string | null;
readonly pages: readonly {
readonly id: string;
readonly label: string;
readonly path: string;
}[];
};
readonly module: {
readonly id: string;
readonly version: string;
@@ -284,7 +295,68 @@ describe("Dashboard navigation — reading", () => {
ui: { url: "/api/v1/module-ui/livestream/1.0.0" },
version: "1.0.0",
});
expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name"]);
expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name", "navigation"]);
// A module that declares no navigation — this manifest v8 fixture — is drawn with the generic
// icon and has its root as its only page (ADR 0063). Never a group or an order.
expect(livestream?.navigation).toEqual({ icon: null, pages: [] });
});
it("carries a manifest v9 module's own icon and pages beside its descriptor, in declared order", async () => {
const { app } = await install({
fixtures: [
{
id: "signage",
name: "Signage",
navigation: {
icon: "monitor-play",
pages: [
{ id: "playback", label: "Playback", path: "playback" },
{ id: "timelines", label: "Timelines", path: "timelines" },
{ id: "media", label: "Media", path: "media" },
],
},
},
{ id: "calendar", name: "Calendar" },
],
principal: signedIn(),
});
const navigation = await navigationOf(app);
const signage = navigation.ungrouped.find((entry) => entry.module.id === "signage");
const calendar = navigation.ungrouped.find((entry) => entry.module.id === "calendar");
expect(signage?.navigation).toEqual({
icon: "monitor-play",
pages: [
{ id: "playback", label: "Playback", path: "playback" },
{ id: "timelines", label: "Timelines", path: "timelines" },
{ id: "media", label: "Media", path: "media" },
],
});
// The host-neutral descriptor is untouched by navigation: it lives beside it, never inside.
expect(Object.keys(signage?.module ?? {}).sort()).toEqual(
Object.keys(calendar?.module ?? {}).sort(),
);
// A manifest v8 module beside it keeps the generic icon and its single root page.
expect(calendar?.navigation).toEqual({ icon: null, pages: [] });
});
it("refuses at discovery a v9 module whose navigation is unsafe, so it never reaches the sidebar", async () => {
const { app } = await install({
fixtures: [
{ id: "calendar", name: "Calendar" },
{
id: "escape",
name: "Escape",
navigation: { pages: [{ id: "out", label: "Out", path: "../settings" }] },
},
],
principal: signedIn(),
}).catch((error: unknown) => ({ app: undefined, error }));
// Discovery is atomic (ADR 0005): an invalid manifest fails the whole inventory rather than
// quietly dropping one module, exactly as for any other manifest error.
expect(app).toBeUndefined();
});
it("agrees exactly with the generic inventory about what is mountable", async () => {
apps/api/tests/module-ui-host-e2e.test.ts
+1
View File
@@ -479,6 +479,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
"contributions",
"display",
"moduleId",
"navigation",
"permissions",
"principal",
"realtime",
apps/api/tests/module-ui-routes.test.ts
+1
View File
@@ -953,6 +953,7 @@ describe("module UI artifact publication — the generic loader consumes what is
contributions: NO_MODULE_UI_CONTRIBUTIONS,
display: undefined,
moduleId: "announcements",
navigation: undefined,
permissions: { has: () => false },
principal: { kind: "anonymous" as const },
realtime: { subscribe: () => ({ close: () => undefined }) },