fix(housekeeping): link only reachable preview routes

src/app/ase-next/[domain]/layout.tsx

@@ -4,9 +4,11 @@ import type { ReactNode } from "react";
 import { satisfiesCapability } from "@/features/housekeeping/foundation/capability-context";
 import { buildHousekeepingNavigation } from "@/features/housekeeping/foundation/navigation";
 import { createHousekeepingRegistry } from "@/features/housekeeping/foundation/registry";
+import { createHousekeepingRouteRuntime } from "@/features/housekeeping/foundation/routing/runtime";
 import { getHousekeepingCapabilityContext } from "@/features/housekeeping/foundation/server-capability-context";
 import { HousekeepingShell } from "@/features/housekeeping/foundation/shell/housekeeping-shell";
 import { HOUSEKEEPING_MANIFESTS } from "@/features/housekeeping/manifests";
+import { HOUSEKEEPING_ROUTE_HANDLERS } from "@/features/housekeeping/route-handlers";
 
 const MESSAGE_PREFIX = "pages.housekeeping.";
 
@@ -27,6 +29,10 @@ export default async function AdminNextDomainLayout({
 }) {
 	const { domain } = await params;
 	const registry = createHousekeepingRegistry(HOUSEKEEPING_MANIFESTS);
+	const runtime = createHousekeepingRouteRuntime(
+		registry,
+		HOUSEKEEPING_ROUTE_HANDLERS,
+	);
 	const activeDomain = registry.domains.find((entry) => entry.id === domain);
 
 	if (!activeDomain) notFound();
@@ -35,7 +41,7 @@ export default async function AdminNextDomainLayout({
 	if (!satisfiesCapability(context, activeDomain.capability)) notFound();
 
 	const translate = await getTranslations("pages.housekeeping");
-	const navigation = buildHousekeepingNavigation(registry, context, (key) =>
+	const navigation = buildHousekeepingNavigation(runtime, context, (key) =>
 		translate(namespaceKey(key) as never),
 	);
 

src/features/housekeeping/foundation/navigation.test.ts

@@ -1,11 +1,17 @@
 import { describe, expect, it, vi } from "vitest";
 import { PERMS } from "@/lib/permission-slugs";
 import { HOUSEKEEPING_MANIFESTS } from "../manifests";
-import { anyCapability, type HousekeepingCapabilityContext } from "./contracts";
+import {
+	anyCapability,
+	type HousekeepingCapabilityContext,
+	type HousekeepingDomainManifest,
+} from "./contracts";
 import { buildHousekeepingNavigation } from "./navigation";
 import { createHousekeepingRegistry } from "./registry";
+import type { HousekeepingRouteHandler } from "./routing/route-handler";
+import { createHousekeepingRouteRuntime } from "./routing/runtime";
 
-const context = (
+const capabilityContext = (
 	granted: readonly string[],
 ): HousekeepingCapabilityContext => ({
 	actor: { id: 42, username: "moderator", rank: 3 },
@@ -15,159 +21,168 @@ const context = (
 	hasAll: (...slugs) => slugs.every((slug) => granted.includes(slug)),
 });
 
-describe("housekeeping navigation", () => {
+const peopleManifest = {
-	it("shows People to a moderator with a mod view capability while hiding Economy", () => {
+	id: "people",
-		const registry = createHousekeepingRegistry([
+	labelKey: "people.title",
-			{
+	descriptionKey: "people.description",
-				id: "people",
+	iconId: "users",
-				labelKey: "pages.housekeeping.domains.people.title",
+	previewHref: "/ase-next/people",
-				descriptionKey: "pages.housekeeping.domains.people.description",
+	capability: anyCapability(
-				iconId: "users",
+		PERMS.USERS_VIEW,
-				previewHref: "/ase-next/people",
+		PERMS.TICKETS_VIEW,
-				capability: anyCapability(PERMS.MOD_CFH_VIEW),
+		PERMS.BANS_VIEW,
-				landingRouteId: null,
+	),
-				routes: [],
+	landingRouteId: "people.users",
-				searchProviders: [],
+	routes: [
-				inboxSources: [],
+		{
-				widgets: [],
+			id: "people.users",
-			},
+			labelKey: "people.users",
-			{
+			href: "/ase-next/people/users",
-				id: "economy",
+			capability: anyCapability(PERMS.USERS_VIEW),
-				labelKey: "pages.housekeeping.domains.economy.title",
+		},
-				descriptionKey: "pages.housekeeping.domains.economy.description",
+		{
-				iconId: "gem",
+			id: "people.user-detail",
-				previewHref: "/ase-next/economy",
+			labelKey: "people.userDetail",
-				capability: anyCapability(PERMS.CATALOG_VIEW),
+			href: "/ase-next/people/users/:id",
-				landingRouteId: null,
+			capability: anyCapability(PERMS.USERS_VIEW),
-				routes: [],
+		},
-				searchProviders: [],
+		{
-				inboxSources: [],
+			id: "people.tickets",
-				widgets: [],
+			labelKey: "people.tickets",
-			},
+			href: "/ase-next/people/support/tickets",
-		]);
+			capability: anyCapability(PERMS.TICKETS_VIEW),
+		},
+	],
+	searchProviders: [],
+	inboxSources: [],
+	widgets: [],
+} satisfies HousekeepingDomainManifest;
 
+const handler = (routeId: string): HousekeepingRouteHandler => ({
+	routeId,
+	render: async () => `Rendered ${routeId}`,
+});
+
+const peopleRuntime = createHousekeepingRouteRuntime(
+	createHousekeepingRegistry([peopleManifest]),
+	peopleManifest.routes.map((route) => handler(route.id)),
+);
+const identityTranslate = (key: string) => key;
+
+describe("housekeeping navigation", () => {
+	it("links a domain to its accessible handled landing route", () => {
 		const navigation = buildHousekeepingNavigation(
-			registry,
+			peopleRuntime,
-			context([PERMS.MOD_CFH_VIEW]),
+			capabilityContext([PERMS.USERS_VIEW]),
-			(key) => key,
+			identityTranslate,
 		);
 
 		expect(navigation).toEqual([
 			{
 				id: "people",
-				href: "/ase-next/people",
+				href: "/ase-next/people/users",
 				iconId: "users",
-				label: "pages.housekeeping.domains.people.title",
+				label: "people.title",
-				description: "pages.housekeeping.domains.people.description",
+				description: "people.description",
-				items: [],
+				items: [
+					{
+						id: "people.users",
+						href: "/ase-next/people/users",
+						label: "people.users",
+					},
+				],
 			},
 		]);
 	});
 
-	it("filters unauthorized domains and routes before translation", () => {
+	it("falls back to the first accessible handled route", () => {
-		const registry = createHousekeepingRegistry([
+		const navigation = buildHousekeepingNavigation(
-			{
+			peopleRuntime,
-				id: "people",
+			capabilityContext([PERMS.TICKETS_VIEW]),
-				labelKey: "people.title",
+			identityTranslate,
-				descriptionKey: "people.description",
+		);
-				iconId: "users",
+
-				previewHref: "/ase-next/people",
+		expect(navigation[0]?.href).toBe("/ase-next/people/support/tickets");
-				capability: anyCapability(PERMS.USERS_VIEW),
+		expect(navigation[0]?.items.map((item) => item.id)).toEqual([
-				landingRouteId: "users",
+			"people.tickets",
-				routes: [
-					{
-						id: "users",
-						labelKey: "people.users",
-						href: "/ase-next/people/users",
-						capability: anyCapability(PERMS.USERS_VIEW),
-					},
-					{
-						id: "bans",
-						labelKey: "people.bans",
-						href: "/ase-next/people/bans",
-						capability: anyCapability(PERMS.BANS_VIEW),
-					},
-				],
-				searchProviders: [],
-				inboxSources: [],
-				widgets: [],
-			},
-			{
-				id: "system",
-				labelKey: "system.title",
-				descriptionKey: "system.description",
-				iconId: "settings",
-				previewHref: "/ase-next/system",
-				capability: anyCapability(PERMS.SETTINGS_VIEW),
-				landingRouteId: null,
-				routes: [],
-				searchProviders: [],
-				inboxSources: [],
-				widgets: [],
-			},
 		]);
+	});
+
+	it("omits a domain with no accessible handled concrete route", () => {
+		expect(
+			buildHousekeepingNavigation(
+				peopleRuntime,
+				capabilityContext([PERMS.BANS_VIEW]),
+				identityTranslate,
+			),
+		).toEqual([]);
+	});
+
+	it("does not expose dynamic route patterns as navigation links", () => {
+		const navigation = buildHousekeepingNavigation(
+			peopleRuntime,
+			capabilityContext([PERMS.USERS_VIEW]),
+			identityTranslate,
+		);
+
+		expect(navigation[0]?.items.map((item) => item.id)).not.toContain(
+			"people.user-detail",
+		);
+		expect(navigation[0]?.items.map((item) => item.href)).not.toContain(
+			"/ase-next/people/users/:id",
+		);
+	});
+
+	it("filters inaccessible routes before translation", () => {
 		const translate = vi.fn((key: string) => `translated:${key}`);
 
-		const navigation = buildHousekeepingNavigation(
+		buildHousekeepingNavigation(
-			registry,
+			peopleRuntime,
-			context([PERMS.USERS_VIEW]),
+			capabilityContext([PERMS.TICKETS_VIEW]),
 			translate,
 		);
 
-		expect(navigation).toEqual([
+		expect(translate).toHaveBeenCalledWith("people.title");
-			{
+		expect(translate).toHaveBeenCalledWith("people.description");
-				id: "people",
+		expect(translate).toHaveBeenCalledWith("people.tickets");
-				href: "/ase-next/people",
+		expect(translate).not.toHaveBeenCalledWith("people.users");
-				iconId: "users",
+		expect(translate).not.toHaveBeenCalledWith("people.userDetail");
-				label: "translated:people.title",
-				description: "translated:people.description",
-				items: [
-					{
-						id: "users",
-						href: "/ase-next/people/users",
-						label: "translated:people.users",
-					},
-				],
-			},
-		]);
-		expect(translate).not.toHaveBeenCalledWith("people.bans");
-		expect(translate).not.toHaveBeenCalledWith("system.title");
-		expect(translate).not.toHaveBeenCalledWith("system.description");
 	});
-	it("shows real domains to operators authorized by owned migration capabilities", () => {
+
-		const registry = createHousekeepingRegistry(HOUSEKEEPING_MANIFESTS);
+	it("keeps current empty manifests out of navigation until a vertical ships", () => {
-		const translate = (key: string) => key;
+		const emptyRuntime = createHousekeepingRouteRuntime(
+			createHousekeepingRegistry(HOUSEKEEPING_MANIFESTS),
+			[],
+		);
 
 		expect(
 			buildHousekeepingNavigation(
-				registry,
+				emptyRuntime,
-				context([PERMS.MOD_CFH_VIEW]),
+				capabilityContext([PERMS.MOD_CFH_VIEW]),
-				translate,
+				identityTranslate,
-			).map((domain) => domain.id),
+			),
-		).toContain("people");
+		).toEqual([]);
-		expect(
+	});
-			buildHousekeepingNavigation(
-				registry,
-				context([PERMS.MOD_CFH_VIEW]),
-				translate,
-			).map((domain) => domain.id),
-		).not.toContain("economy");
 
-		for (const [slug, expectedDomain] of [
+	it("projects only hrefs that the runtime can resolve", () => {
-			[PERMS.MOD_ACTIONS, "people"],
+		const capabilityProfiles = [
-			[PERMS.USERS_EDIT, "people"],
+			capabilityContext([PERMS.USERS_VIEW]),
-			[PERMS.SETTINGS_VIEW, "people"],
+			capabilityContext([PERMS.TICKETS_VIEW]),
-			[PERMS.NEWS_EDIT, "content"],
+			capabilityContext([PERMS.BANS_VIEW]),
-			[PERMS.SHOP_EDIT, "economy"],
+			capabilityContext([PERMS.USERS_VIEW, PERMS.TICKETS_VIEW]),
-			[PERMS.ROOMS_EDIT, "hotel"],
+		];
-		] as const) {
-			const visibleDomainIds = buildHousekeepingNavigation(
-				registry,
-				context([slug]),
-				translate,
-			).map((domain) => domain.id);
 
-			expect(visibleDomainIds, slug).toContain(expectedDomain);
+		for (const profile of capabilityProfiles) {
+			for (const domain of buildHousekeepingNavigation(
+				peopleRuntime,
+				profile,
+				identityTranslate,
+			)) {
+				expect(peopleRuntime.match(domain.href), domain.href).not.toBeNull();
+				for (const item of domain.items) {
+					expect(peopleRuntime.match(item.href), item.href).not.toBeNull();
+				}
+			}
 		}
 	});
 });

src/features/housekeeping/foundation/navigation.ts

@@ -3,37 +3,63 @@ import { satisfiesCapability } from "./capability-context";
 import type {
 	HousekeepingCapabilityContext,
 	HousekeepingDomainManifest,
+	HousekeepingPreviewHref,
 } from "./contracts";
-import type { HousekeepingRegistry } from "./registry";
+import type { HousekeepingRouteRuntime } from "./routing/runtime";
 
 export interface HousekeepingNavigationDomain {
 	id: HousekeepingDomainId;
-	href: string;
+	href: HousekeepingPreviewHref;
 	iconId: HousekeepingDomainManifest["iconId"];
 	label: string;
 	description: string;
-	items: readonly { id: string; href: string; label: string }[];
+	items: readonly {
+		id: string;
+		href: HousekeepingPreviewHref;
+		label: string;
+	}[];
 }
 
 export function buildHousekeepingNavigation(
-	registry: HousekeepingRegistry,
+	runtime: HousekeepingRouteRuntime,
 	context: HousekeepingCapabilityContext,
 	translate: (key: string) => string,
 ): readonly HousekeepingNavigationDomain[] {
-	return registry.domains
+	return runtime.registry.domains.flatMap((domain) => {
-		.filter((domain) => satisfiesCapability(context, domain.capability))
+		if (!satisfiesCapability(context, domain.capability)) return [];
-		.map((domain) => ({
+
-			id: domain.id,
+		const items = domain.routes
-			href: domain.previewHref,
+			.filter(
-			iconId: domain.iconId,
+				(route) =>
-			label: translate(domain.labelKey),
+					runtime.handlers.has(route.id) &&
-			description: translate(domain.descriptionKey),
+					isConcreteNavigationHref(route.href) &&
-			items: domain.routes
+					satisfiesCapability(context, route.capability),
-				.filter((route) => satisfiesCapability(context, route.capability))
+			)
-				.map((route) => ({
+			.map((route) => ({
-					id: route.id,
+				id: route.id,
-					href: route.href,
+				href: route.href,
-					label: translate(route.labelKey),
+				label: translate(route.labelKey),
-				})),
+			}));
-		}));
+
+		if (items.length === 0) return [];
+
+		const landing =
+			items.find((item) => item.id === domain.landingRouteId) ?? items[0];
+		if (!landing) return [];
+
+		return [
+			{
+				id: domain.id,
+				href: landing.href,
+				iconId: domain.iconId,
+				label: translate(domain.labelKey),
+				description: translate(domain.descriptionKey),
+				items,
+			},
+		];
+	});
+}
+
+function isConcreteNavigationHref(href: HousekeepingPreviewHref): boolean {
+	return !href.split("/").some((segment) => segment.startsWith(":"));
 }

src/features/housekeeping/foundation/preview-route-contract.test.ts

@@ -483,7 +483,7 @@ describe("/ase-next/[domain] layout", () => {
 		expect(routeMocks.getTranslations).not.toHaveBeenCalled();
 	});
 
-	it("renders localized People shell from one refreshed capability context", async () => {
+	it("renders the shell without exposing a domain that has no concrete routes", async () => {
 		routeMocks.getHousekeepingCapabilityContext.mockResolvedValue(
 			capabilityContext([PERMS.MOD_CFH_VIEW]),
 		);
@@ -502,9 +502,12 @@ describe("/ase-next/[domain] layout", () => {
 		expect(html).toContain("HK::command-disabled");
 		expect(html).toContain("HK::preview-badge");
 		expect(html).toContain("HK::back-to-site");
-		expect(html).toContain("HK::people-title");
+		expect(html).not.toContain("HK::people-title");
 		expect(html).toContain("People body");
 		expect(html).not.toContain("Localized Economy");
+		expect(routeMocks.translate).not.toHaveBeenCalledWith(
+			"domains.people.title",
+		);
 		expect(routeMocks.translate).not.toHaveBeenCalledWith(
 			"domains.economy.title",
 		);

src/features/housekeeping/foundation/shell/housekeeping-shell.test.tsx

@@ -17,7 +17,7 @@ const labels = {
 const domains: readonly HousekeepingNavigationDomain[] = [
 	{
 		id: "operations",
-		href: "/ase-next/operations",
+		href: "/ase-next/operations/queue",
 		iconId: "inbox",
 		label: "Operations",
 		description: "Manage operations",
@@ -27,7 +27,7 @@ const domains: readonly HousekeepingNavigationDomain[] = [
 	},
 	{
 		id: "people",
-		href: "/ase-next/people",
+		href: "/ase-next/people/users",
 		iconId: "users",
 		label: "People",
 		description: "Manage people",
@@ -35,7 +35,7 @@ const domains: readonly HousekeepingNavigationDomain[] = [
 	},
 	{
 		id: "content",
-		href: "/ase-next/content",
+		href: "/ase-next/content/articles",
 		iconId: "file-text",
 		label: "Content",
 		description: "Manage content",
@@ -43,7 +43,7 @@ const domains: readonly HousekeepingNavigationDomain[] = [
 	},
 	{
 		id: "economy",
-		href: "/ase-next/economy",
+		href: "/ase-next/economy/catalog",
 		iconId: "gem",
 		label: "Economy",
 		description: "Manage economy",
@@ -51,7 +51,7 @@ const domains: readonly HousekeepingNavigationDomain[] = [
 	},
 	{
 		id: "hotel",
-		href: "/ase-next/hotel",
+		href: "/ase-next/hotel/rooms",
 		iconId: "hotel",
 		label: "Hotel",
 		description: "Manage hotel",
@@ -59,7 +59,7 @@ const domains: readonly HousekeepingNavigationDomain[] = [
 	},
 	{
 		id: "system",
-		href: "/ase-next/system",
+		href: "/ase-next/system/settings",
 		iconId: "settings",
 		label: "System",
 		description: "Manage system",
@@ -196,7 +196,7 @@ describe("HousekeepingShell", () => {
 		const activeAnchors = allAnchors.filter((anchor) =>
 			anchor.includes('aria-current="page"'),
 		);
-		const peopleAnchor = anchorForHref(html, "/ase-next/people");
+		const peopleAnchor = anchorForHref(html, "/ase-next/people/users");
 		for (const iconClass of [
 			"lucide-inbox",
 			"lucide-users",
@@ -222,7 +222,7 @@ describe("HousekeepingShell", () => {
 		);
 		expect(() => renderShell("system", domainsWithoutSystem)).not.toThrow();
 		const html = renderShell("system", domainsWithoutSystem);
-		expect(html).not.toContain('href="/ase-next/operations/queue"');
+		expect(html.match(/href="\/ase-next\/operations\/queue"/g)).toHaveLength(1);
 		expect(html).not.toContain(">Queue<");
 	});
 

src/features/housekeeping/route-handlers.ts

@@ -0,0 +1,4 @@
+import type { HousekeepingRouteHandler } from "./foundation/routing/route-handler";
+
+export const HOUSEKEEPING_ROUTE_HANDLERS =
+	[] as const satisfies readonly HousekeepingRouteHandler[];