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]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
ac5b2b7f6c
commit
bd34c9c714
@@ -0,0 +1,415 @@
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { Client, type QueryResultRow } from "pg";
|
||||
import { afterAll, describe, expect, it } from "vitest";
|
||||
import {
|
||||
createDashboardDrizzleView,
|
||||
createDashboardStore,
|
||||
type DashboardStore,
|
||||
DashboardStoreError,
|
||||
resolveDashboardNavigation,
|
||||
} from "../src/dashboard/index.js";
|
||||
import { createValidatedPostgresPool } from "../src/database/index.js";
|
||||
import {
|
||||
applyModuleMigrations,
|
||||
createPostgresMigrationDatabase,
|
||||
discoverAllMigrations,
|
||||
} from "../src/migrations/index.js";
|
||||
|
||||
/**
|
||||
* The Dashboard navigation store against real PostgreSQL.
|
||||
*
|
||||
* The unit suites prove the resolution rules; this proves the things only a database can: that the
|
||||
* migration really creates these tables, that configuration survives a completely new connection,
|
||||
* that `on delete set null` really ungroups a deleted group's modules, and that a placement can
|
||||
* never point at a group that does not exist. The in-memory double used by the API route tests
|
||||
* deliberately reproduces only two of those behaviours, so this file is where they are actually
|
||||
* established rather than assumed.
|
||||
*/
|
||||
const integrationDatabaseUrlEnvironment = "EKKLESIA_MIGRATION_TEST_DATABASE_URL";
|
||||
const coreMigrationsDirectory = path.join(
|
||||
path.dirname(fileURLToPath(import.meta.url)),
|
||||
"..",
|
||||
"drizzle",
|
||||
);
|
||||
const trackedDatabases = new Set<string>();
|
||||
let databaseCounter = 0;
|
||||
|
||||
class IntegrationHarnessError extends Error {
|
||||
constructor(message: string) {
|
||||
super(message);
|
||||
this.name = "IntegrationHarnessError";
|
||||
this.stack = `${this.name}: ${this.message}`;
|
||||
}
|
||||
}
|
||||
|
||||
function harnessError(message: string): IntegrationHarnessError {
|
||||
return new IntegrationHarnessError(message);
|
||||
}
|
||||
|
||||
function baseDatabaseUrl(): string {
|
||||
const value = process.env[integrationDatabaseUrlEnvironment];
|
||||
if (typeof value !== "string" || value.trim() === "") {
|
||||
throw harnessError("The Dashboard integration database is not configured.");
|
||||
}
|
||||
try {
|
||||
const parsed = new URL(value);
|
||||
if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:") {
|
||||
throw new TypeError("Unsupported protocol.");
|
||||
}
|
||||
} catch {
|
||||
throw harnessError("The Dashboard integration database configuration is invalid.");
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function quoteDatabaseName(databaseName: string): string {
|
||||
if (!/^[a-z][a-z0-9_]{0,62}$/u.test(databaseName)) {
|
||||
throw harnessError("The generated integration database name is invalid.");
|
||||
}
|
||||
return `"${databaseName}"`;
|
||||
}
|
||||
|
||||
function makeDatabaseName(label: string): string {
|
||||
const safeLabel = label
|
||||
.toLowerCase()
|
||||
.replaceAll(/[^a-z0-9]+/gu, "_")
|
||||
.replaceAll(/^_+|_+$/gu, "")
|
||||
.slice(0, 14);
|
||||
databaseCounter += 1;
|
||||
return `ekk_dash_${process.pid}_${databaseCounter}_${safeLabel || "scenario"}_${randomBytes(4).toString("hex")}`;
|
||||
}
|
||||
|
||||
function databaseUrl(databaseName: string): string {
|
||||
const parsed = new URL(baseDatabaseUrl());
|
||||
parsed.pathname = `/${databaseName}`;
|
||||
parsed.searchParams.delete("application_name");
|
||||
return parsed.toString();
|
||||
}
|
||||
|
||||
async function openAdministrativeClient(connectionString: string): Promise<Client> {
|
||||
const client = new Client({ connectionString });
|
||||
client.on("error", () => undefined);
|
||||
try {
|
||||
await client.connect();
|
||||
return client;
|
||||
} catch {
|
||||
try {
|
||||
await client.end();
|
||||
} catch {
|
||||
// The public harness failure stays static when connection cleanup also fails.
|
||||
}
|
||||
throw harnessError("The Dashboard integration database connection failed.");
|
||||
}
|
||||
}
|
||||
|
||||
async function safeQuery<Row extends QueryResultRow>(
|
||||
client: Client,
|
||||
text: string,
|
||||
values: unknown[] = [],
|
||||
): Promise<readonly Row[]> {
|
||||
try {
|
||||
const result = await client.query<Row>(text, values);
|
||||
return result.rows;
|
||||
} catch {
|
||||
throw harnessError("An integration database administration operation failed.");
|
||||
}
|
||||
}
|
||||
|
||||
async function safeEnd(client: Client): Promise<void> {
|
||||
try {
|
||||
await client.end();
|
||||
} catch {
|
||||
throw harnessError("An integration database connection could not be closed.");
|
||||
}
|
||||
}
|
||||
|
||||
async function dropDatabase(databaseName: string): Promise<void> {
|
||||
const admin = await openAdministrativeClient(baseDatabaseUrl());
|
||||
try {
|
||||
await safeQuery(
|
||||
admin,
|
||||
"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()",
|
||||
[databaseName],
|
||||
);
|
||||
await safeQuery(
|
||||
admin,
|
||||
`DROP DATABASE IF EXISTS ${quoteDatabaseName(databaseName)} WITH (FORCE)`,
|
||||
);
|
||||
trackedDatabases.delete(databaseName);
|
||||
} finally {
|
||||
await safeEnd(admin);
|
||||
}
|
||||
}
|
||||
|
||||
async function createDisposableDatabase(label: string): Promise<{ name: string; url: string }> {
|
||||
const name = makeDatabaseName(label);
|
||||
const admin = await openAdministrativeClient(baseDatabaseUrl());
|
||||
try {
|
||||
await safeQuery(admin, `CREATE DATABASE ${quoteDatabaseName(name)} TEMPLATE template0`);
|
||||
} finally {
|
||||
await safeEnd(admin);
|
||||
}
|
||||
trackedDatabases.add(name);
|
||||
return { name, url: databaseUrl(name) };
|
||||
}
|
||||
|
||||
async function applyCoreMigrations(url: string): Promise<void> {
|
||||
const emptyModulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-dash-no-modules-"));
|
||||
try {
|
||||
const aggregate = await discoverAllMigrations({
|
||||
coreMigrationsDirectory,
|
||||
moduleDiscovery: {
|
||||
moduleSdkVersion: "0.1.0",
|
||||
modulesDirectory: emptyModulesDirectory,
|
||||
platformVersion: "0.1.0",
|
||||
},
|
||||
});
|
||||
expect(aggregate.migrations.map((entry) => entry.identity)).toEqual([
|
||||
"core:0000_identity_core_tables",
|
||||
"core:0001_authorization_core_tables",
|
||||
"core:0002_authorization_integrity",
|
||||
"core:0003_dashboard_navigation_tables",
|
||||
]);
|
||||
await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
|
||||
} finally {
|
||||
await rm(emptyModulesDirectory, { force: true, recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
afterAll(async () => {
|
||||
for (const databaseName of [...trackedDatabases]) {
|
||||
await dropDatabase(databaseName).catch(() => undefined);
|
||||
}
|
||||
});
|
||||
|
||||
describe.sequential("live Core Dashboard navigation store", () => {
|
||||
let database: { name: string; url: string };
|
||||
let admin: Client;
|
||||
let store: DashboardStore;
|
||||
let close: () => Promise<void>;
|
||||
|
||||
it("creates exactly the two Dashboard tables, with their constraints", async () => {
|
||||
database = await createDisposableDatabase("fresh");
|
||||
await applyCoreMigrations(database.url);
|
||||
admin = await openAdministrativeClient(database.url);
|
||||
|
||||
const tables = await safeQuery<{ table_name: string }>(
|
||||
admin,
|
||||
`select table_name from information_schema.tables
|
||||
where table_schema = 'public' and table_name like 'ekklesia_core_dashboard%'
|
||||
order by table_name`,
|
||||
);
|
||||
const constraints = await safeQuery<{ constraint_name: string; delete_rule: string }>(
|
||||
admin,
|
||||
`select rc.constraint_name, rc.delete_rule
|
||||
from information_schema.referential_constraints rc
|
||||
join information_schema.table_constraints tc
|
||||
on tc.constraint_name = rc.constraint_name
|
||||
where tc.table_name = 'ekklesia_core_dashboard_placement'`,
|
||||
);
|
||||
|
||||
expect(tables.map((table) => table.table_name)).toEqual([
|
||||
"ekklesia_core_dashboard_group",
|
||||
"ekklesia_core_dashboard_placement",
|
||||
]);
|
||||
// The database, not the application, is what guarantees a deleted group leaves no dangling
|
||||
// reference.
|
||||
expect(constraints.map((constraint) => constraint.delete_rule)).toEqual(["SET NULL"]);
|
||||
|
||||
const handle = createValidatedPostgresPool(database.url);
|
||||
close = handle.close;
|
||||
store = createDashboardStore(createDashboardDrizzleView(handle.pool));
|
||||
});
|
||||
|
||||
it("starts empty, so an installation with no configuration is a normal state", async () => {
|
||||
expect(await store.readConfiguration()).toEqual({ groups: [], placements: [] });
|
||||
});
|
||||
|
||||
it("persists groups and placements, and reads them back in deterministic order", async () => {
|
||||
await store.upsertGroup({ id: "planning", label: "Planning", sortOrder: 20 });
|
||||
await store.upsertGroup({ id: "media", label: "Media", sortOrder: 10 });
|
||||
await store.setPlacement({ groupId: "media", moduleId: "livestream", sortOrder: 20 });
|
||||
await store.setPlacement({ groupId: "media", moduleId: "video", sortOrder: 10 });
|
||||
await store.setPlacement({ groupId: "planning", moduleId: "calendar", sortOrder: 10 });
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
|
||||
expect(configuration.groups.map((group) => group.id)).toEqual(["media", "planning"]);
|
||||
expect(configuration.placements.map((placement) => placement.moduleId)).toEqual([
|
||||
"calendar",
|
||||
"video",
|
||||
"livestream",
|
||||
]);
|
||||
});
|
||||
|
||||
it("survives a completely new connection, so a church configures its Dashboard once", async () => {
|
||||
// A different pool, as a restarted process would use — nothing is cached in the old one.
|
||||
const reopened = createValidatedPostgresPool(database.url);
|
||||
try {
|
||||
const configuration = await createDashboardStore(
|
||||
createDashboardDrizzleView(reopened.pool),
|
||||
).readConfiguration();
|
||||
const view = resolveDashboardNavigation(configuration, [
|
||||
{ id: "livestream", name: "Livestream" },
|
||||
{ id: "video", name: "Video" },
|
||||
{ id: "calendar", name: "Calendar" },
|
||||
]);
|
||||
|
||||
expect(
|
||||
view.groups.map((group) => [group.label, group.modules.map((entry) => entry.name)]),
|
||||
).toEqual([
|
||||
["Media", ["Video", "Livestream"]],
|
||||
["Planning", ["Calendar"]],
|
||||
]);
|
||||
} finally {
|
||||
await reopened.close();
|
||||
}
|
||||
});
|
||||
|
||||
it("renames a group without disturbing a single placement", async () => {
|
||||
const before = await store.readConfiguration();
|
||||
|
||||
await store.upsertGroup({ id: "media", label: "Media & Streaming", sortOrder: 10 });
|
||||
const after = await store.readConfiguration();
|
||||
|
||||
expect(after.groups.find((group) => group.id === "media")?.label).toBe("Media & Streaming");
|
||||
// The stable id is what placements point at, so a rename can never re-organize the Dashboard.
|
||||
expect(after.placements).toEqual(before.placements);
|
||||
});
|
||||
|
||||
it("re-orders a group and a module in place, without creating duplicates", async () => {
|
||||
await store.upsertGroup({ id: "media", label: "Media & Streaming", sortOrder: 30 });
|
||||
await store.setPlacement({ groupId: "media", moduleId: "video", sortOrder: 99 });
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
|
||||
expect(configuration.groups).toHaveLength(2);
|
||||
expect(configuration.groups.map((group) => group.id)).toEqual(["planning", "media"]);
|
||||
expect(configuration.placements.filter((entry) => entry.moduleId === "video")).toHaveLength(1);
|
||||
expect(configuration.placements.find((entry) => entry.moduleId === "video")?.sortOrder).toBe(
|
||||
99,
|
||||
);
|
||||
});
|
||||
|
||||
it("moves a module between groups by changing exactly one row", async () => {
|
||||
await store.upsertGroup({ id: "sunday-production", label: "Sunday Production", sortOrder: 5 });
|
||||
await store.setPlacement({
|
||||
groupId: "sunday-production",
|
||||
moduleId: "livestream",
|
||||
sortOrder: 10,
|
||||
});
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
|
||||
expect(configuration.placements.find((entry) => entry.moduleId === "livestream")?.groupId).toBe(
|
||||
"sunday-production",
|
||||
);
|
||||
// Video did not move.
|
||||
expect(configuration.placements.find((entry) => entry.moduleId === "video")?.groupId).toBe(
|
||||
"media",
|
||||
);
|
||||
});
|
||||
|
||||
it("ungroups a module deliberately, which is distinct from having no record", async () => {
|
||||
await store.setPlacement({ groupId: null, moduleId: "calendar", sortOrder: 7 });
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
const calendar = configuration.placements.find((entry) => entry.moduleId === "calendar");
|
||||
|
||||
expect(calendar).toEqual({ groupId: null, moduleId: "calendar", sortOrder: 7 });
|
||||
});
|
||||
|
||||
it("ungroups a deleted group's modules instead of leaving a dangling reference", async () => {
|
||||
await store.deleteGroup("sunday-production");
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
const groupIds = new Set(configuration.groups.map((group) => group.id));
|
||||
|
||||
expect(groupIds.has("sunday-production")).toBe(false);
|
||||
expect(
|
||||
configuration.placements.find((entry) => entry.moduleId === "livestream")?.groupId,
|
||||
).toBeNull();
|
||||
// No placement anywhere names a group that no longer exists.
|
||||
for (const placement of configuration.placements) {
|
||||
if (placement.groupId !== null) {
|
||||
expect(groupIds.has(placement.groupId)).toBe(true);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("refuses a placement naming a group that was never created", async () => {
|
||||
await expect(
|
||||
store.setPlacement({ groupId: "not-a-group", moduleId: "video", sortOrder: 10 }),
|
||||
).rejects.toMatchObject({ code: "DASHBOARD_GROUP_NOT_FOUND" });
|
||||
});
|
||||
|
||||
it("refuses to delete a group that does not exist", async () => {
|
||||
await expect(store.deleteGroup("not-a-group")).rejects.toMatchObject({
|
||||
code: "DASHBOARD_GROUP_NOT_FOUND",
|
||||
});
|
||||
});
|
||||
|
||||
it("stores a placement for a module that is not installed, and renders nothing for it", async () => {
|
||||
await store.upsertGroup({ id: "media", label: "Media & Streaming", sortOrder: 30 });
|
||||
await store.setPlacement({ groupId: "media", moduleId: "uninstalled", sortOrder: 1 });
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
const view = resolveDashboardNavigation(configuration, [{ id: "video", name: "Video" }]);
|
||||
|
||||
// Retained, so a reinstall restores the position...
|
||||
expect(configuration.placements.map((entry) => entry.moduleId)).toContain("uninstalled");
|
||||
// ...and never rendered while the module is absent.
|
||||
expect(
|
||||
[...view.groups.flatMap((group) => group.modules), ...view.ungrouped].map(
|
||||
(entry) => entry.id,
|
||||
),
|
||||
).toEqual(["video"]);
|
||||
});
|
||||
|
||||
it("rejects malformed input before it reaches the database", async () => {
|
||||
await expect(
|
||||
store.upsertGroup({ id: "Not Kebab Case", label: "Nope", sortOrder: 0 }),
|
||||
).rejects.toBeInstanceOf(DashboardStoreError);
|
||||
await expect(
|
||||
store.upsertGroup({ id: "media", label: " ", sortOrder: 0 }),
|
||||
).rejects.toMatchObject({ code: "DASHBOARD_GROUP_LABEL_INVALID" });
|
||||
await expect(
|
||||
store.upsertGroup({ id: "media", label: "x".repeat(121), sortOrder: 0 }),
|
||||
).rejects.toMatchObject({ code: "DASHBOARD_GROUP_LABEL_INVALID" });
|
||||
await expect(
|
||||
store.upsertGroup({ id: "media", label: "Media", sortOrder: -1 }),
|
||||
).rejects.toMatchObject({ code: "DASHBOARD_SORT_ORDER_INVALID" });
|
||||
await expect(
|
||||
store.setPlacement({ groupId: null, moduleId: "Not Valid", sortOrder: 0 }),
|
||||
).rejects.toMatchObject({ code: "DASHBOARD_MODULE_ID_INVALID" });
|
||||
await expect(
|
||||
store.setPlacement({ groupId: null, moduleId: "video", sortOrder: 1.5 }),
|
||||
).rejects.toMatchObject({ code: "DASHBOARD_SORT_ORDER_INVALID" });
|
||||
});
|
||||
|
||||
it("trims a stored label rather than persisting surrounding whitespace", async () => {
|
||||
await store.upsertGroup({ id: "planning", label: " Planning ", sortOrder: 20 });
|
||||
|
||||
const configuration = await store.readConfiguration();
|
||||
|
||||
expect(configuration.groups.find((group) => group.id === "planning")?.label).toBe("Planning");
|
||||
});
|
||||
|
||||
it("leaks no database detail in a sanitized failure", async () => {
|
||||
await close();
|
||||
|
||||
const error = await store.readConfiguration().catch((caught: unknown) => caught);
|
||||
const text = `${String(error)}\n${(error as Error).stack ?? ""}`;
|
||||
|
||||
expect(error).toMatchObject({ code: "DASHBOARD_READ_FAILED" });
|
||||
expect(text).not.toContain(database.name);
|
||||
expect(text).not.toContain("select");
|
||||
expect(text).not.toContain("ekklesia_core_dashboard");
|
||||
await safeEnd(admin);
|
||||
await dropDatabase(database.name);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user