Ekklesia/surfaces/shell/tests/dashboard-routes.test.ts

// @vitest-environment node
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import {
  ACCOUNT_SECTIONS,
  DASHBOARD_PLATFORM_PAGES,
  dashboardPathReturningTo,
  HOST_NAMESPACES,
  parseModuleRoute,
  returnTargetFromSearch,
  dashboardPath,
  parseDashboardPath,
  DISCOVER_CHILD_VIEWS,
  DISCOVER_VIEWS,
  SETTINGS_SECTIONS,
} from "../src/dashboard-routes.js";

const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));

describe("the Dashboard's own top-level pages", () => {
  it("are exactly Settings and Account, frozen", () => {
    expect(Object.isFrozen(DASHBOARD_PLATFORM_PAGES)).toBe(true);
    expect(DASHBOARD_PLATFORM_PAGES).toEqual(["settings", "account"]);
  });
});

describe("parseDashboardPath", () => {
  it("makes the root the Overview", () => {
    expect(parseDashboardPath("/")).toEqual({ kind: "overview" });
  });

  it("names a module page by its id at the top level, tolerating one trailing slash", () => {
    expect(parseDashboardPath("/signage")).toEqual({
      kind: "module",
      moduleId: "signage",
      path: "",
    });
    expect(parseDashboardPath("/signage/")).toEqual({
      kind: "module",
      moduleId: "signage",
      path: "",
    });
    expect(parseDashboardPath("/people")).toEqual({ kind: "module", moduleId: "people", path: "" });
  });

  it("decodes a percent-encoded segment, so an id is compared as the server spells it", () => {
    expect(parseDashboardPath("/sign%61ge")).toEqual({
      kind: "module",
      moduleId: "signage",
      path: "",
    });
  });

  it("never reads a platform page as a module page", () => {
    expect(parseDashboardPath("/settings")).toEqual({ kind: "settings" });
    expect(parseDashboardPath("/account")).toEqual({ kind: "account" });
  });

  it("reads the account area: the account page and its personal settings pages (ADR 0062)", () => {
    expect(parseDashboardPath("/account")).toEqual({ kind: "account" });
    expect(parseDashboardPath("/account/")).toEqual({ kind: "account" });
    expect(parseDashboardPath("/account/appearance")).toEqual({
      kind: "account-section",
      section: "appearance",
    });
    expect(parseDashboardPath("/account/appearance/")).toEqual({
      kind: "account-section",
      section: "appearance",
    });
    expect(dashboardPath({ kind: "account" })).toBe("/account");
    expect(dashboardPath({ kind: "account-section", section: "appearance" })).toBe(
      "/account/appearance",
    );
    expect(ACCOUNT_SECTIONS).toEqual(["appearance"]);
    for (const pathname of [
      "/account/profile",
      "/account/appearance/extra",
      "/account/Appearance",
      "/account//appearance",
      "/accounts",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual(
        pathname === "/accounts"
          ? { kind: "module", moduleId: "accounts", path: "" }
          : { kind: "not-found" },
      );
    }
  });

  it("treats every other shape as not found rather than guessing", () => {
    for (const pathname of [
      "",
      "//",
      "//signage",
      "/signage//",
      "/signage/a//b",
      "/%E0%A4%A",
      // The host's non-Dashboard namespaces are never pages, however deep (ADR 0063).
      "/api",
      "/api/v1/principal",
      "/assets/ekklesia-dashboard/app.js",
      "/display/signage",
      // Deeper Settings pages are reserved for later (ADR 0061).
      "/settings/displays/add",
      "/settings/signage/timelines",
      "/settings//signage",
      "signage",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual({ kind: "not-found" });
    }
  });
});

describe("Settings routes (ADR 0061)", () => {
  it("names exactly the platform's own Settings sections, frozen", () => {
    expect(Object.isFrozen(SETTINGS_SECTIONS)).toBe(true);
    expect(SETTINGS_SECTIONS).toEqual(["general", "branding", "displays", "discover", "system"]);
    expect(Object.isFrozen(DISCOVER_VIEWS)).toBe(true);
    expect(DISCOVER_VIEWS).toEqual(["browse", "installed", "updates"]);
  });

  it("has a landing page of its own, tolerating one trailing slash", () => {
    expect(parseDashboardPath("/settings")).toEqual({ kind: "settings" });
    expect(parseDashboardPath("/settings/")).toEqual({ kind: "settings" });
  });

  it("reads each platform section, and nothing else, as a platform section", () => {
    for (const section of ["general", "branding", "displays", "system"] as const) {
      expect(parseDashboardPath(`/settings/${section}`), section).toEqual({
        kind: "settings-section",
        section,
      });
    }
  });

  it("reads Discover's own page at /settings/discover, and Installed and Updates beneath it", () => {
    expect(DISCOVER_CHILD_VIEWS).toEqual(["installed", "updates"]);
    // Discover itself is where modules are found and installed (ADR 0064): one canonical address.
    expect(parseDashboardPath("/settings/discover")).toEqual({ kind: "discover", view: "browse" });
    expect(parseDashboardPath("/settings/discover/")).toEqual({ kind: "discover", view: "browse" });
    expect(dashboardPath({ kind: "discover", view: "browse" })).toBe("/settings/discover");
    for (const view of DISCOVER_CHILD_VIEWS) {
      expect(parseDashboardPath(`/settings/discover/${view}`), view).toEqual({
        kind: "discover",
        view,
      });
      expect(dashboardPath({ kind: "discover", view }), view).toBe(`/settings/discover/${view}`);
    }
    for (const pathname of [
      "/settings/discover/catalog",
      "/settings/discover/browse/signage",
      "/settings/discover/installed/signage",
      "/settings/discover//",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual({ kind: "not-found" });
    }
  });

  it("still reads the earlier /settings/discover/browse, only as an alias the shell respells", () => {
    // A bookmark from before ADR 0064 keeps working: it reads as Discover's own page, whose one
    // canonical spelling is `/settings/discover`, so the shell replaces it in place.
    expect(parseDashboardPath("/settings/discover/browse")).toEqual({
      kind: "discover",
      view: "browse",
    });
    expect(dashboardPath(parseDashboardPath("/settings/discover/browse") as never)).toBe(
      "/settings/discover",
    );
  });

  it("reads every other name as a module's settings — never under /settings/modules/", () => {
    expect(parseDashboardPath("/settings/signage")).toEqual({
      kind: "module-settings",
      moduleId: "signage",
    });
    expect(parseDashboardPath("/settings/sign%61ge/")).toEqual({
      kind: "module-settings",
      moduleId: "signage",
    });
    expect(parseDashboardPath("/settings/modules/signage")).toEqual({ kind: "not-found" });
    // `modules` is no longer a platform section, so it is simply a module id like any other.
    expect(parseDashboardPath("/settings/modules")).toEqual({
      kind: "module-settings",
      moduleId: "modules",
    });
  });

  it("spells each Settings destination canonically and round-trips it", () => {
    for (const [route, path] of [
      [{ kind: "settings" }, "/settings"],
      [{ kind: "settings-section", section: "displays" }, "/settings/displays"],
      [{ kind: "discover", view: "installed" }, "/settings/discover/installed"],
      [{ kind: "module-settings", moduleId: "signage" }, "/settings/signage"],
    ] as const) {
      expect(dashboardPath(route)).toBe(path);
      expect(parseDashboardPath(path)).toEqual(route);
    }
  });
});

describe("dashboardPath", () => {
  it("spells each route canonically, with no implementation prefix", () => {
    expect(dashboardPath({ kind: "overview" })).toBe("/");
    expect(dashboardPath({ kind: "module", moduleId: "signage", path: "" })).toBe("/signage");
  });

  it("encodes a module id so it can never escape its own segment", () => {
    expect(dashboardPath({ kind: "module", moduleId: "a/../b", path: "" })).toBe("/a%2F..%2Fb");
    expect(
      parseDashboardPath(dashboardPath({ kind: "module", moduleId: "a/../b", path: "" })),
    ).toEqual({
      kind: "module",
      moduleId: "a/../b",
      path: "",
    });
  });

  it("round-trips through the parser", () => {
    for (const route of [
      { kind: "overview" } as const,
      { kind: "module", moduleId: "example", path: "" } as const,
      { kind: "module", moduleId: "example", path: "records" } as const,
      { kind: "module", moduleId: "media", path: "sermons/2026-10-11_service~1.mp4" } as const,
    ]) {
      expect(parseDashboardPath(dashboardPath(route))).toEqual(route);
    }
  });
});

describe("module routes (ADR 0063)", () => {
  it("reads everything beneath a module's root as that module's own route", () => {
    expect(parseDashboardPath("/signage/timelines")).toEqual({
      kind: "module",
      moduleId: "signage",
      path: "timelines",
    });
    expect(parseDashboardPath("/signage/timelines/")).toEqual({
      kind: "module",
      moduleId: "signage",
      path: "timelines",
    });
    expect(parseDashboardPath("/media/sermons/123")).toEqual({
      kind: "module",
      moduleId: "media",
      path: "sermons/123",
    });
  });

  it("spells a module route canonically, its path beneath the encoded module id", () => {
    expect(dashboardPath({ kind: "module", moduleId: "signage", path: "timelines" })).toBe(
      "/signage/timelines",
    );
    expect(dashboardPath({ kind: "module", moduleId: "signage", path: "" })).toBe("/signage");
  });

  it.each([
    ["", ""],
    ["/", ""],
    ["timelines", "timelines"],
    ["/timelines", "timelines"],
    ["media/sermons/123", "media/sermons/123"],
    ["a.b_c~d-e", "a.b_c~d-e"],
  ])("accepts the module route %j as %j", (input, expected) => {
    expect(parseModuleRoute(input)).toBe(expected);
  });

  it.each([
    "../calendar",
    "media/../../settings",
    "./timelines",
    "media/.",
    "//evil.example.test",
    "https://evil.example.test",
    "javascript:alert(1)",
    "timelines?x=1",
    "timelines#top",
    "media%2F..%2Fapi",
    "media\\library",
    "media//library",
    "timelines/",
    "time lines",
    "a/b/c/d/e/f/g/h/i",
    `${"a".repeat(513)}`,
  ])("refuses the module route %j", (input) => {
    expect(parseModuleRoute(input)).toBeUndefined();
  });

  it("refuses anything that is not a string", () => {
    for (const value of [undefined, null, 1, ["timelines"], { path: "timelines" }]) {
      expect(parseModuleRoute(value)).toBeUndefined();
    }
  });

  it("names exactly the host's non-Dashboard namespaces", () => {
    expect(HOST_NAMESPACES).toEqual(["api", "assets", "display"]);
  });

  it("carries a return target on its own query parameter, readable only as a raw value", () => {
    const href = dashboardPathReturningTo(
      { kind: "module-settings", moduleId: "signage" },
      { kind: "module", moduleId: "signage", path: "timelines" },
    );
    expect(href).toBe("/settings/signage?return=%2Fsignage%2Ftimelines");
    expect(returnTargetFromSearch("?return=%2Fsignage%2Ftimelines")).toBe("/signage/timelines");
    expect(returnTargetFromSearch("")).toBeUndefined();
    expect(returnTargetFromSearch("?other=1")).toBeUndefined();
  });
});

describe("the route locator is published for the API that serves the page", () => {
  it("is a narrow package subpath, not the shell root barrel", async () => {
    const manifest = JSON.parse(
      await readFile(path.join(packageDirectory, "package.json"), "utf8"),
    ) as { exports?: Record<string, unknown> };
    expect(manifest.exports?.["./dashboard-routes"]).toEqual({
      import: "./dist/dashboard-routes.js",
      types: "./dist/dashboard-routes.d.ts",
    });
  });
});