feat: add Dashboard navigation as presentation configuration

Phase 6D pass 1. The shell's navigation was a flat list of module ids, which is not a usable experience — and the obvious fix carries an obvious trap. Letting a module declare its folder, or modelling "Media" as something Livestream and Video belong to, turns a rendering preference into architecture: a folder becomes an owner, membership starts to look like a dependency, and the flat module graph acquires a hierarchy nobody decided on. So the rule comes first: a Dashboard group is a label on a rendering bucket. No manifest, no version, no artifact, no API, no lifecycle; nothing depends on it. Livestream depends on Video because it calls Video's functionality, and that orders startup. Livestream is shown under Media, and that orders nothing. No parent module, child module, owning module, or group-derived dependency appears anywhere in the contracts. No manifest change and no version 5. `manifest.name` has been required since version 1 and already is the module's product identity, so the shell renders "Livestream" instead of `livestream` with nothing added. `suggestedGroup` is deliberately deferred rather than shipped: it would force a hard manifest-version cutover for a hint, and its only correct semantics needs initialization logic that risks a suggestion overwriting an administrator's decision. Defaulting and ownership are different things. Two Core tables (migration 0003) hold groups and placements — server-side, because a church configures its Dashboard rather than one browser; platform-global, because no organization model exists to scope them to. `group_id` is `on delete set null`, so deleting a group ungroups its modules and a dangling reference is impossible. `module_id` carries no foreign key, because modules are packages rather than rows, so a placement for an uninstalled module is retained and restores its position on reinstall. `resolveDashboardNavigation` is a pure function of configuration plus the mountable set: an unplaced module is ungrouped and visible with no initialization write, an absent module renders nothing, empty groups are kept, and ordering is total with the module id as final tie-break. `GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of the host-neutral module UI inventory rather than merged into it — each generic descriptor is embedded untouched, so a standalone host never inherits Dashboard semantics. Reading needs the permission the inventory already needs; organizing needs the new platform permission `core.dashboard.navigation.manage` through a narrow, idempotent, closed-validation mutation contract. No editor UI. The flatness rule is executable: a test discovers real fixtures with a genuine dependency, arranges them four ways including both in one folder and the dependency inverted in presentation, and asserts discovery order, dependency declarations, and the module set stay byte-identical. The end-to-end test organizes a real installation through the real API, mounts a module from inside a group, moves it, and asserts the navigation entry is byte-identical across the move and still mounts the same artifact. The shell's client for the generic inventory became dead code and was removed rather than kept speculatively; the endpoint itself is unchanged. Co-Authored-By: Claude Opus 5 <[email protected]>
2026-08-22 12:44:40 -05:00
parent ac5b2b7f6c
commit bd34c9c714
49 changed files with 4866 additions and 213 deletions
@@ -1,11 +1,10 @@
 import { describe, expect, it, vi } from "vitest";
 import {
  bootstrapHost,
-  type EkklesiaHostConfig,
  type HostModuleUiDescriptor,
+  loadDashboardNavigation,
  loadHostPrincipal,
-  loadModuleUiInventory,
-  parseHostModuleUiInventory,
+  parseDashboardNavigation,
  parseHostPrincipal,
 } from "../src/host-protocol.js";
 import { createModuleUiContext, moduleUiSourceUrl } from "../src/module-context.js";
@@ -47,6 +46,37 @@ const inventoryPayload = {
  ],
 };

+const calendarDescriptor: HostModuleUiDescriptor = {
+  apiBaseUrl: "/api/v1/modules/calendar",
+  id: "calendar",
+  permissions: [],
+  uiUrl: "/api/v1/module-ui/calendar/2.0.0",
+  version: "2.0.0",
+};
+
+const navigationPayload = {
+  groups: [
+    {
+      id: "media",
+      label: "Media",
+      modules: [{ module: inventoryPayload.modules[0], name: "Example Module" }],
+      order: 10,
+    },
+  ],
+  ungrouped: [
+    {
+      module: {
+        api: { baseUrl: "/api/v1/modules/calendar" },
+        id: "calendar",
+        permissions: [],
+        ui: { url: "/api/v1/module-ui/calendar/2.0.0" },
+        version: "2.0.0",
+      },
+      name: "Calendar",
+    },
+  ],
+};
+
 const exampleDescriptor: HostModuleUiDescriptor = {
  apiBaseUrl: "/api/v1/modules/example",
  id: "example",
@@ -55,69 +85,57 @@ const exampleDescriptor: HostModuleUiDescriptor = {
  version: "0.1.0",
 };

-describe("host protocol — inventory", () => {
-  it("parses the server's descriptor into exactly what a host context needs", () => {
-    expect(parseHostModuleUiInventory(inventoryPayload)).toEqual([exampleDescriptor]);
+function navigationWithModule(module: unknown): unknown {
+  return { groups: [], ungrouped: [{ module, name: "Example Module" }] };
+}
+
+describe("host protocol — descriptor validation", () => {
+  it("parses a well-formed descriptor out of the navigation view", () => {
+    const navigation = parseDashboardNavigation(navigationWithModule(inventoryPayload.modules[0]));
+
+    expect(navigation.ungrouped[0]?.descriptor).toEqual(exampleDescriptor);
  });

-  it("rejects a malformed document rather than yielding a half-built descriptor", () => {
+  it("rejects a malformed descriptor rather than yielding a half-built one", () => {
+    const base = inventoryPayload.modules[0] as Record<string, unknown>;
    const malformed: unknown[] = [
      {},
-      { modules: {} },
-      { modules: [{ id: "example", version: "0.1.0" }] },
-      { modules: [{ ...inventoryPayload.modules[0], ui: {} }] },
-      { modules: [{ ...inventoryPayload.modules[0], api: { baseUrl: "" } }] },
-      { modules: [{ ...inventoryPayload.modules[0], permissions: "example.records.read" }] },
-      { modules: [{ ...inventoryPayload.modules[0], permissions: [42] }] },
+      { id: "example", version: "0.1.0" },
+      { ...base, ui: {} },
+      { ...base, api: { baseUrl: "" } },
+      { ...base, permissions: "example.records.read" },
+      { ...base, permissions: [42] },
      // Both URLs must be root-relative, so a value that would resolve against another origin is
      // refused rather than silently used to fetch browser code.
-      {
-        modules: [
-          { ...inventoryPayload.modules[0], ui: { url: "https://evil.example.test/x.js" } },
-        ],
-      },
-      { modules: [{ ...inventoryPayload.modules[0], ui: { url: "//evil.example.test/x.js" } }] },
-      { modules: [{ ...inventoryPayload.modules[0], ui: { url: "relative/x.js" } }] },
-      {
-        modules: [
-          { ...inventoryPayload.modules[0], api: { baseUrl: "https://evil.example.test/api" } },
-        ],
-      },
+      { ...base, ui: { url: "https://evil.example.test/x.js" } },
+      { ...base, ui: { url: "//evil.example.test/x.js" } },
+      { ...base, ui: { url: "relative/x.js" } },
+      { ...base, api: { baseUrl: "https://evil.example.test/api" } },
    ];
-    for (const payload of malformed) {
-      expect(() => parseHostModuleUiInventory(payload)).toThrowError(
-        expect.objectContaining({ code: "HOST_RESPONSE_INVALID" }),
-      );
+    for (const module of malformed) {
+      expect(
+        () => parseDashboardNavigation(navigationWithModule(module)),
+        JSON.stringify(module),
+      ).toThrowError(expect.objectContaining({ code: "HOST_RESPONSE_INVALID" }));
    }
  });

-  it("fetches the inventory from the platform path with credentials", async () => {
-    const { calls, implementation } = stubFetch({
-      "/api/v1/module-ui": () => jsonResponse(inventoryPayload),
-    });
-    const config: EkklesiaHostConfig = { apiBaseUrl, fetch: implementation };
-
-    await loadModuleUiInventory(config);
-
-    expect(calls[0]?.url).toBe(`${apiBaseUrl}/api/v1/module-ui`);
-    expect(calls[0]?.init?.credentials).toBe("include");
-  });
-
  it("reports an unauthenticated caller distinctly from any other failure", async () => {
    for (const status of [401, 403]) {
      const { implementation } = stubFetch({
-        "/api/v1/module-ui": () => jsonResponse({ code: "AUTHORIZATION_DENIED" }, status),
+        "/api/v1/dashboard/navigation": () =>
+          jsonResponse({ code: "AUTHORIZATION_DENIED" }, status),
      });
      await expect(
-        loadModuleUiInventory({ apiBaseUrl, fetch: implementation }),
+        loadDashboardNavigation({ apiBaseUrl, fetch: implementation }),
      ).rejects.toMatchObject({ code: "HOST_UNAUTHENTICATED" });
    }

    const { implementation } = stubFetch({
-      "/api/v1/module-ui": () => jsonResponse({ code: "INTERNAL_ERROR" }, 500),
+      "/api/v1/dashboard/navigation": () => jsonResponse({ code: "INTERNAL_ERROR" }, 500),
    });
    await expect(
-      loadModuleUiInventory({ apiBaseUrl, fetch: implementation }),
+      loadDashboardNavigation({ apiBaseUrl, fetch: implementation }),
    ).rejects.toMatchObject({ code: "HOST_REQUEST_FAILED" });
  });

@@ -126,7 +144,7 @@ describe("host protocol — inventory", () => {
      throw new Error("connect ECONNREFUSED /run/postgres/.s.PGSQL.5432");
    }) as unknown as typeof fetch;

-    const error = await loadModuleUiInventory({ apiBaseUrl, fetch: failing }).catch(
+    const error = await loadDashboardNavigation({ apiBaseUrl, fetch: failing }).catch(
      (caught: unknown) => caught,
    );

@@ -167,10 +185,63 @@ describe("host protocol — principal", () => {
  });
 });

-describe("host protocol — bootstrap", () => {
-  it("resolves the principal and then the inventory", async () => {
+describe("host protocol — Dashboard navigation", () => {
+  it("parses the server's resolved arrangement, keeping the mount descriptor nested", () => {
+    const navigation = parseDashboardNavigation(navigationPayload);
+
+    expect(navigation.groups.map((group) => [group.id, group.label])).toEqual([["media", "Media"]]);
+    expect(navigation.groups[0]?.modules).toEqual([
+      { descriptor: exampleDescriptor, name: "Example Module" },
+    ]);
+    expect(navigation.ungrouped).toEqual([{ descriptor: calendarDescriptor, name: "Calendar" }]);
+  });
+
+  it("rejects a malformed navigation document rather than rendering half of it", () => {
+    const malformed: unknown[] = [
+      {},
+      { groups: [] },
+      { groups: {}, ungrouped: [] },
+      { groups: [{ id: "media", label: "Media" }], ungrouped: [] },
+      { groups: [{ id: "media", modules: [] }], ungrouped: [] },
+      { groups: [], ungrouped: [{ name: "Example" }] },
+      { groups: [], ungrouped: [{ module: inventoryPayload.modules[0] }] },
+      // An absolute artifact URL must be refused here exactly as in the inventory.
+      {
+        groups: [],
+        ungrouped: [
+          {
+            module: {
+              ...inventoryPayload.modules[0],
+              ui: { url: "https://evil.example.test/x.js" },
+            },
+            name: "Example",
+          },
+        ],
+      },
+    ];
+    for (const payload of malformed) {
+      expect(() => parseDashboardNavigation(payload), JSON.stringify(payload)).toThrowError(
+        expect.objectContaining({ code: "HOST_RESPONSE_INVALID" }),
+      );
+    }
+  });
+
+  it("fetches navigation from the platform path with credentials", async () => {
    const { calls, implementation } = stubFetch({
-      "/api/v1/module-ui": () => jsonResponse(inventoryPayload),
+      "/api/v1/dashboard/navigation": () => jsonResponse(navigationPayload),
+    });
+
+    await loadDashboardNavigation({ apiBaseUrl, fetch: implementation });
+
+    expect(calls[0]?.url).toBe(`${apiBaseUrl}/api/v1/dashboard/navigation`);
+    expect(calls[0]?.init?.credentials).toBe("include");
+  });
+});
+
+describe("host protocol — bootstrap", () => {
+  it("resolves the principal and then the Dashboard navigation", async () => {
+    const { calls, implementation } = stubFetch({
+      "/api/v1/dashboard/navigation": () => jsonResponse(navigationPayload),
      "/api/v1/principal": () => jsonResponse({ kind: "authenticated", userId: "user-1" }),
    });

@@ -178,22 +249,22 @@ describe("host protocol — bootstrap", () => {

    expect(calls.map((call) => call.url)).toEqual([
      `${apiBaseUrl}/api/v1/principal`,
-      `${apiBaseUrl}/api/v1/module-ui`,
+      `${apiBaseUrl}/api/v1/dashboard/navigation`,
    ]);
    expect(bootstrap.principal).toEqual({ kind: "authenticated", userId: "user-1" });
-    expect(bootstrap.modules).toEqual([exampleDescriptor]);
+    expect(bootstrap.navigation.groups[0]?.modules[0]?.descriptor).toEqual(exampleDescriptor);
  });

-  it("never requests the inventory for an anonymous viewer", async () => {
+  it("never requests navigation for an anonymous viewer", async () => {
    const { calls, implementation } = stubFetch({
-      "/api/v1/module-ui": () => jsonResponse(inventoryPayload),
+      "/api/v1/dashboard/navigation": () => jsonResponse(navigationPayload),
      "/api/v1/principal": () => jsonResponse({ kind: "anonymous" }),
    });

    const bootstrap = await bootstrapHost({ apiBaseUrl, fetch: implementation });

    expect(bootstrap.principal).toEqual({ kind: "anonymous" });
-    expect(bootstrap.modules).toEqual([]);
+    expect(bootstrap.navigation).toEqual({ groups: [], ungrouped: [] });
    expect(calls.map((call) => call.url)).toEqual([`${apiBaseUrl}/api/v1/principal`]);
  });