Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,312 @@
import { NavigateFunction } from "react-router";
import { describe, expect, it, vi } from "vitest";
import { getCommandRegistryActions, getSidebarCommandActions } from "./commandRegistry";
const t = vi.fn().mockImplementation((value: string) => value) as any;
const routing = {
protocol: "https",
webAppHost: "app.example.test",
adminAppHost: "admin.example.test",
apiHost: "api.example.test",
appBaseDomain: "example.test",
};
function rootData(tenantApiKeys = true, admin = false, routingConfig?: typeof routing, crm = false) {
return {
appConfiguration: {
app: { features: { tenantApiKeys, crm } },
portals: { enabled: false, forTenants: false },
},
user: { admin },
routing: routingConfig,
} as any;
}
function appData(options?: { admin?: boolean; permissions?: string[]; tenantApiKeys?: boolean }) {
return {
currentTenant: { id: "tenant_1", slug: "acme" },
entities: [
{ name: "company", titlePlural: "models.company.plural", slug: "companies", showInSidebar: true },
{ name: "contact", titlePlural: "models.contact.plural", slug: "contacts", showInSidebar: true },
{ name: "opportunity", titlePlural: "models.opportunity.plural", slug: "opportunities", showInSidebar: true },
],
myTenants: [{ id: "tenant_2", slug: "other" }],
permissions: options?.permissions ?? [
"app.settings.members.view",
"app.settings.subscription.view",
"app.settings.account.view",
"app.settings.apiKeys.view",
"app.settings.auditTrails.view",
"entity.company.view",
"entity.contact.view",
"entity.opportunity.view",
],
isSuperAdmin: false,
user: { id: "user_1", admin: options?.admin ?? true },
} as any;
}
function navigateMock() {
return vi.fn() as unknown as NavigateFunction & { mock: ReturnType<typeof vi.fn>["mock"] };
}
function perform(action: { perform?: (action: any) => void; id: string }) {
action.perform?.({ id: action.id });
}
function expectNoLegacyPrefixes(targets: string[]) {
targets.forEach((target) => {
expect(target).not.toMatch(/^\/app\//);
expect(target).not.toMatch(/^\/admin(?:\/|$)/);
});
}
describe("command registry", () => {
it("builds app tenant commands with host-aware tenant URLs and scope metadata", () => {
const navigate = navigateMock();
const actions = getCommandRegistryActions({ layout: "app", t, navigate, appData: appData(), rootData: rootData() });
perform(actions.find((action) => action.id === "dashboard")!);
perform(actions.find((action) => action.id === "members")!);
perform(actions.find((action) => action.id === "apiKeys")!);
expect(navigate).toHaveBeenNthCalledWith(1, "/acme/dashboard");
expect(navigate).toHaveBeenNthCalledWith(2, "/acme/settings/members");
expect(navigate).toHaveBeenNthCalledWith(3, "/acme/settings/api");
expect(actions.find((action) => action.id === "members")?.scope).toMatchObject({
layout: "app",
tenantSlug: "acme",
permission: "app.settings.members.view",
});
expect(actions.find((action) => action.id === "apiKeys")?.scope).toMatchObject({ featureFlag: "tenantApiKeys", permission: "app.settings.apiKeys.view" });
expectNoLegacyPrefixes(navigate.mock.calls.map(([target]) => target));
});
it("omits app commands for empty app data", () => {
expect(getCommandRegistryActions({ layout: "app", t, navigate: navigateMock(), rootData: rootData() })).toEqual([]);
});
it("filters tenant settings commands by permissions and feature flags", () => {
const actions = getCommandRegistryActions({
layout: "app",
t,
navigate: navigateMock(),
appData: appData({ permissions: ["app.settings.account.view"] }),
rootData: rootData(false),
});
expect(actions.some((action) => action.id === "account")).toBe(true);
expect(actions.some((action) => action.id === "members")).toBe(false);
expect(actions.some((action) => action.id === "subscription")).toBe(false);
expect(actions.some((action) => action.id === "apiKeys")).toBe(false);
expect(actions.some((action) => action.id === "auditTrails")).toBe(false);
expect(actions.some((action) => action.id === "events")).toBe(false);
});
it("filters tenant entity commands through permission-aware scope metadata", () => {
const actions = getCommandRegistryActions({
layout: "app",
t,
navigate: navigateMock(),
appData: appData({ permissions: ["entity.company.view"] }),
rootData: rootData(),
});
expect(actions.find((action) => action.id === "entity-company")?.scope).toMatchObject({
layout: "app",
tenantSlug: "acme",
permission: "entity.company.view",
});
expect(actions.some((action) => action.id === "entity-contact")).toBe(false);
expect(actions.some((action) => action.id === "entity-opportunity")).toBe(false);
});
it("omits CRM command while the CRM route tree is disabled", () => {
const disabled = getCommandRegistryActions({
layout: "app",
t,
navigate: navigateMock(),
appData: appData(),
rootData: rootData(true, true, routing, false),
});
const enabled = getCommandRegistryActions({
layout: "app",
t,
navigate: navigateMock(),
appData: appData(),
rootData: rootData(true, true, routing, true),
});
expect(disabled.some((action) => action.id === "crm")).toBe(false);
expect(enabled.some((action) => action.id === "crm")).toBe(false);
});
it("keeps platform commands available when scoped tenant commands are denied", () => {
const actions = getCommandRegistryActions({
layout: "app",
t,
navigate: navigateMock(),
appData: appData({ admin: false, permissions: [] }),
rootData: rootData(),
});
expect(actions.some((action) => action.id === "entity-company")).toBe(false);
expect(actions.some((action) => action.id === "create account")).toBe(true);
expect(actions.some((action) => action.id === "logout")).toBe(true);
});
it("omits switch-to-admin for non-admin app users", () => {
const actions = getCommandRegistryActions({ layout: "app", t, navigate: navigateMock(), appData: appData({ admin: false }), rootData: rootData() });
expect(actions.some((action) => action.id === "switch to admin")).toBe(false);
});
it("switches app admins to the admin dashboard instead of the admin host root", () => {
const navigate = navigateMock();
const actions = getCommandRegistryActions({ layout: "app", t, navigate, appData: appData({ admin: true }), rootData: rootData(true, true, routing) });
vi.stubGlobal("window", undefined);
try {
perform(actions.find((action) => action.id === "switch to admin")!);
} finally {
vi.unstubAllGlobals();
}
expect(navigate).toHaveBeenCalledWith("https://admin.example.test/dashboard");
});
it("filters admin sidebar commands for non-superadmin contexts while preserving platform commands", () => {
const actions = getCommandRegistryActions({ layout: "admin", t, navigate: navigateMock(), rootData: rootData() });
expect(actions.some((action) => action.id === "/dashboard")).toBe(false);
expect(actions.some((action) => action.id === "create account")).toBe(true);
expect(actions.some((action) => action.id === "logout")).toBe(true);
});
it("builds admin commands when app data has no current tenant", () => {
const actions = getCommandRegistryActions({
layout: "admin",
t,
navigate: navigateMock(),
appData: { ...appData({ admin: true }), currentTenant: null, isSuperAdmin: true } as any,
rootData: rootData(true, true),
});
expect(actions.some((action) => action.id === "/dashboard")).toBe(true);
expect(actions.every((action) => action.scope.layout === "admin")).toBe(true);
});
it("builds admin commands with host-aware paths and app fallback switch", () => {
const navigate = navigateMock();
const actions = getCommandRegistryActions({ layout: "admin", t, navigate, rootData: rootData(true, true) });
perform(actions.find((action) => action.id === "/dashboard")!);
perform(actions.find((action) => action.id === "/settings/profile")!);
perform(actions.find((action) => action.name === "admin.switchToApp")!);
expect(navigate).toHaveBeenNthCalledWith(1, "/dashboard");
expect(navigate).toHaveBeenNthCalledWith(2, "/settings/profile");
expect(navigate).toHaveBeenNthCalledWith(3, "/");
expect(actions.find((action) => action.id === "/dashboard")?.scope).toMatchObject({ layout: "admin", platform: true, adminOnly: true });
expect(actions.find((action) => action.name === "admin.switchToApp")?.scope).toMatchObject({ layout: "admin", platform: true, adminOnly: true });
expectNoLegacyPrefixes(navigate.mock.calls.map(([target]) => target));
});
it("does not expose expandable admin sidebar parents as command destinations", () => {
const actions = getCommandRegistryActions({
layout: "admin",
t,
navigate: navigateMock(),
appData: {
...appData({
admin: true,
permissions: ["admin.accounts.view", "admin.settings.view"],
}),
currentTenant: null,
isSuperAdmin: true,
} as any,
rootData: rootData(true, true),
});
expect(actions.some((action) => action.id === "/accounts" && action.name === "app.sidebar.accountsAndUsers")).toBe(false);
expect(actions.some((action) => action.id === "/settings" && action.name === "app.sidebar.settings")).toBe(false);
expect(actions.some((action) => action.id === "/accounts" && action.name === "admin.tenants.title")).toBe(true);
expect(actions.some((action) => action.id === "/settings/profile")).toBe(true);
});
it("does not expose disabled sidebar items as command destinations", () => {
const actions = getSidebarCommandActions(
[
{
title: "Settings",
path: "/settings",
items: [
{ title: "Profile", path: "/settings/profile" },
{ title: "Disabled Plugin", path: "/settings/plugin", disabled: true },
],
},
],
"admin"
);
expect(actions.some((action) => action.id === "/settings/profile")).toBe(true);
expect(actions.some((action) => action.id === "/settings/plugin")).toBe(false);
});
it("uses parent sidebar titles as command subtitles", () => {
const actions = getSidebarCommandActions(
[
{
title: "Settings",
path: "/settings",
items: [{ title: "Profile", path: "/settings/profile" }],
},
],
"admin"
);
expect(actions.find((action) => action.id === "/settings/profile")?.subtitle).toBe("Settings");
});
it("builds admin public-app commands with absolute app-host URLs when routing is configured", () => {
const navigate = navigateMock();
const actions = getCommandRegistryActions({ layout: "admin", t, navigate, rootData: rootData(true, true, routing) });
expect(actions.find((action) => action.name === "admin.switchToApp")?.id).toBe("https://app.example.test/");
vi.stubGlobal("window", undefined);
try {
perform(actions.find((action) => action.name === "admin.switchToApp")!);
perform(actions.find((action) => action.id === "create account")!);
} finally {
vi.unstubAllGlobals();
}
expect(navigate).toHaveBeenNthCalledWith(1, "https://app.example.test/");
expect(navigate).toHaveBeenNthCalledWith(2, "https://app.example.test/new-account");
});
it("passes docs commands through with registry scope and navigation", () => {
const navigate = navigateMock();
const actions = getCommandRegistryActions({ layout: "docs", t, navigate });
const firstAction = actions[0];
perform(firstAction);
expect(firstAction.scope).toMatchObject({ layout: "docs", platform: true });
expect(navigate).toHaveBeenCalledWith(firstAction.id);
});
it("exposes app, admin, and docs commands directly through the registry", () => {
expect(getCommandRegistryActions({ layout: "app", t, navigate: navigateMock(), appData: appData(), rootData: rootData() })[0]).toMatchObject({
id: "dashboard",
scope: { layout: "app" },
});
expect(getCommandRegistryActions({ layout: "admin", t, navigate: navigateMock(), rootData: rootData(true, true) })[0]).toMatchObject({
id: "/dashboard",
scope: { layout: "admin" },
});
expect(getCommandRegistryActions({ layout: "docs", t, navigate: navigateMock() })[0]).toMatchObject({ scope: { layout: "docs" } });
});
});
@@ -0,0 +1,304 @@
import type { ReactNode } from "react";
import { TFunction, i18n } from "i18next";
import { NavigateFunction } from "react-router";
import { AdminSidebar } from "~/application/sidebar/AdminSidebar";
import { SideBarItem } from "~/application/sidebar/SidebarItem";
import { getUserHasPermission } from "~/utils/helpers/PermissionsHelper";
import { AppLoaderData } from "~/utils/data/useAppData";
import { AppRootData } from "~/utils/data/useRootData";
import { getDocCommands } from "~/utils/services/docsService";
import { appPath } from "~/utils/app/CanonicalUrlUtils";
import { absoluteAdminPath, absoluteAppRootPath, isAbsoluteHttpUrl, type PublicDomainRoutingConfig } from "~/utils/app/CrossHostUrls";
import { filterCommandActions } from "~/services/search/commandSearch";
import { translateLabel } from "~/utils/i18n/translateLabel";
// Registry marker: services/command-registry paths are app-relative for package verification.
export type CommandRegistryLayout = "app" | "admin" | "docs";
export type CommandActionScope = {
layout: CommandRegistryLayout;
tenantSlug?: string;
platform?: boolean;
adminOnly?: boolean;
featureFlag?: string;
permission?: string;
};
export type CommandAction = {
id: string;
name: string;
subtitle?: string;
keywords?: string;
shortcut?: string[];
icon?: ReactNode;
perform?: (currentAction: CommandAction) => void;
};
export type ScopedCommandAction = CommandAction & {
scope: CommandActionScope;
};
export type CommandRegistryContext = {
layout: CommandRegistryLayout;
t: TFunction;
i18n?: Pick<i18n, "exists">;
navigate: NavigateFunction;
submitLogout?: () => void;
appData?: AppLoaderData;
rootData?: AppRootData;
};
export function getCommandRegistryActions(context: CommandRegistryContext): ScopedCommandAction[] {
const actions = getUnfilteredCommandRegistryActions(context);
return filterCommandActions({
actions,
query: "",
layout: context.layout,
tenantSlug: context.appData?.currentTenant?.slug,
appData: context.appData,
rootData: context.rootData,
});
}
function getUnfilteredCommandRegistryActions(context: CommandRegistryContext): ScopedCommandAction[] {
if (context.layout === "app") {
return getAppCommandActions(context);
}
if (context.layout === "admin") {
return getAdminCommandActions(context);
}
return getDocsCommandActions(context);
}
function getAppCommandActions({ t, i18n, navigate, submitLogout, appData, rootData }: CommandRegistryContext): ScopedCommandAction[] {
if (!appData || !rootData) {
return [];
}
const tenantSlug = appData.currentTenant.slug;
const tenantPath = (path?: string) => appPath({ tenantSlug, path, mode: "host-aware" });
const tenantScope = (metadata?: Omit<CommandActionScope, "layout" | "tenantSlug">): CommandActionScope => ({ layout: "app", tenantSlug, ...metadata });
const actions: ScopedCommandAction[] = [
{
id: "dashboard",
shortcut: [],
name: t("app.sidebar.dashboard"),
keywords: "",
scope: tenantScope(),
perform: () => navigate(tenantPath("dashboard")),
},
];
appData.entities
.filter((entity) => entity.showInSidebar)
.forEach((entity) => {
const permission = typeof entity.name === "string" && entity.name.trim() ? `entity.${entity.name}.view` : undefined;
actions.push({
id: "entity-" + entity.name,
name: translateLabel(t, i18n, entity.titlePlural),
scope: tenantScope({ permission }),
perform: () => navigate(tenantPath(entity.slug)),
});
});
actions.push({
id: "profile",
shortcut: [],
name: t("app.commands.profile.title"),
subtitle: t("app.sidebar.settings"),
keywords: t("app.commands.profile.description"),
scope: tenantScope(),
perform: () => navigate(tenantPath("settings/profile")),
});
pushPermissionAction(actions, appData, "app.settings.members.view", {
id: "members",
name: t("app.navbar.members"),
shortcut: [],
keywords: "",
subtitle: t("app.sidebar.settings"),
scope: tenantScope({ permission: "app.settings.members.view" }),
perform: () => navigate(tenantPath("settings/members")),
});
pushPermissionAction(actions, appData, "app.settings.subscription.view", {
id: "subscription",
name: t("app.navbar.subscription"),
shortcut: [],
keywords: "",
subtitle: t("app.sidebar.settings"),
scope: tenantScope({ permission: "app.settings.subscription.view" }),
perform: () => navigate(tenantPath("settings/subscription")),
});
pushPermissionAction(actions, appData, "app.settings.account.view", {
id: "account",
name: t("app.navbar.tenant"),
shortcut: [],
keywords: "",
subtitle: t("app.sidebar.settings"),
scope: tenantScope({ permission: "app.settings.account.view" }),
perform: () => navigate(tenantPath("settings/account")),
});
if (rootData.appConfiguration.app.features.tenantApiKeys) {
pushPermissionAction(actions, appData, "app.settings.apiKeys.view", {
id: "apiKeys",
name: t("models.apiKey.plural"),
shortcut: [],
keywords: "",
subtitle: t("app.sidebar.settings"),
scope: tenantScope({ featureFlag: "tenantApiKeys", permission: "app.settings.apiKeys.view" }),
perform: () => navigate(tenantPath("settings/api")),
});
}
if (getUserHasPermission(appData, "app.settings.auditTrails.view")) {
actions.push({
id: "auditTrails",
name: t("models.log.plural"),
shortcut: [],
keywords: "",
subtitle: t("app.sidebar.settings"),
scope: tenantScope({ permission: "app.settings.auditTrails.view" }),
perform: () => navigate(tenantPath("settings/logs")),
});
actions.push({
id: "events",
name: t("models.event.plural"),
shortcut: [],
keywords: "",
subtitle: t("app.sidebar.settings"),
scope: tenantScope({ permission: "app.settings.auditTrails.view" }),
perform: () => navigate(tenantPath("settings/logs/events")),
});
}
if (appData.myTenants.length > 0) {
actions.push({
id: "switch account",
shortcut: [],
name: t("app.commands.tenants.switch"),
keywords: t("app.commands.tenants.description"),
scope: { layout: "app", platform: true },
perform: () => navigateOrAssign(absoluteAppRootPath(rootData.routing), navigate),
});
}
actions.push({
id: "create account",
shortcut: [],
name: t("app.commands.tenants.create"),
keywords: "",
scope: { layout: "app", platform: true },
perform: () => navigateOrAssign(absolutePublicAppPath(rootData.routing, "new-account"), navigate),
});
if (appData.user?.admin) {
actions.push({
id: "switch to admin",
shortcut: [],
name: t("admin.switchToAdmin"),
keywords: "",
scope: { layout: "app", platform: true, adminOnly: true },
perform: () => navigateOrAssign(absoluteAdminPath(rootData.routing, "dashboard"), navigate),
});
}
actions.push({
id: "logout",
shortcut: [],
name: t("app.commands.profile.logout"),
scope: { layout: "app", platform: true },
perform: () => submitLogout?.(),
});
return actions;
}
function pushPermissionAction(actions: ScopedCommandAction[], appData: AppLoaderData, permission: string, action: ScopedCommandAction) {
if (getUserHasPermission(appData, permission as never)) {
actions.push(action);
}
}
function getAdminCommandActions({ t, navigate, submitLogout, rootData }: CommandRegistryContext): ScopedCommandAction[] {
if (!rootData) {
return [];
}
const actions = getSidebarCommandActions(AdminSidebar({ t, appConfiguration: rootData.appConfiguration, routing: rootData.routing }), "admin").map(
(action) => ({
...action,
perform(currentAction: CommandAction) {
navigateOrAssign(currentAction.id, navigate);
},
})
);
actions.push({
id: "create account",
shortcut: [],
name: t("app.commands.tenants.create"),
keywords: "",
scope: { layout: "admin", platform: true },
perform: () => navigateOrAssign(absolutePublicAppPath(rootData.routing, "new-account"), navigate),
});
actions.push({
id: "logout",
shortcut: [],
name: t("app.commands.profile.logout"),
scope: { layout: "admin", platform: true },
perform: () => submitLogout?.(),
});
return actions;
}
function navigateOrAssign(target: string, navigate: NavigateFunction) {
if (isAbsoluteHttpUrl(target) && typeof window !== "undefined") {
window.location.assign(target);
return;
}
navigate(target);
}
function absolutePublicAppPath(routing: PublicDomainRoutingConfig | undefined, path: string) {
const appRoot = absoluteAppRootPath(routing);
const cleanPath = path.replace(/^\/+/, "");
if (isAbsoluteHttpUrl(appRoot)) {
return new URL(cleanPath, appRoot).toString();
}
return `/${cleanPath}`;
}
function getDocsCommandActions({ navigate }: CommandRegistryContext): ScopedCommandAction[] {
return getDocCommands().map((action) => ({
...action,
scope: { layout: "docs", platform: true },
perform(currentAction) {
navigate(currentAction.id);
},
}));
}
export function getSidebarCommandActions(items: SideBarItem[], layout: CommandRegistryLayout): ScopedCommandAction[] {
const commands: ScopedCommandAction[] = [];
items.forEach((item) => commands.push(...getCommandsFromSidebarItem(item, layout, [], [])));
return commands;
}
function getCommandsFromSidebarItem(item: SideBarItem, layout: CommandRegistryLayout, commands: ScopedCommandAction[], parent: string[]) {
if (item.hidden || item.disabled) {
return commands;
}
const isExpandableOnlyParent = item.isCollapsible && item.items && item.items.length > 0;
if (item.path && item.title && !isExpandableOnlyParent) {
let description = item.description ?? "";
const parentTitles = parent.filter((value) => value);
if (parentTitles.length > 0) {
description = parentTitles.join(" / ");
}
commands.push({
id: item.path,
name: item.title,
shortcut: [],
subtitle: description,
scope: { layout, platform: true, adminOnly: layout === "admin", permission: item.permission },
});
}
item.items?.forEach((subItem) => getCommandsFromSidebarItem(subItem, layout, commands, [...parent, item.title]));
return commands;
}