feat: rebuild onboarding experience

packages/definitions/src/test/api-key-url.spec.ts

@@ -1,8 +1,16 @@
 import { describe, expect, it } from "vitest";
 
-import { getIntegrationApiKeyUrl } from "../integration";
+import { getIntegrationApiKeyUrl, integrationDefs } from "../integration";
 
 describe("getIntegrationApiKeyUrl", () => {
+  it("links every user-facing integration to its Homarr setup guide", () => {
+    expect(
+      Object.entries(integrationDefs)
+        .filter(([kind, definition]) => kind !== "mock" && !definition.documentationUrl)
+        .map(([kind]) => kind),
+    ).toEqual([]);
+  });
+
   it("builds URL for sonarr", () => {
     expect(getIntegrationApiKeyUrl("http://192.168.1.10:8989", "sonarr")).toBe(
       "http://192.168.1.10:8989/settings/general",
@@ -21,10 +29,28 @@ describe("getIntegrationApiKeyUrl", () => {
     );
   });
 
-  it("returns null for integrations without apiKeySettingsPath", () => {
-    expect(getIntegrationApiKeyUrl("http://localhost", "plex")).toBeNull();
+  it.each([
+    ["homeAssistant", "http://homeassistant.local:8123", "http://homeassistant.local:8123/profile/security"],
+    ["opnsense", "https://firewall.local", "https://firewall.local/system_usermanager.php"],
+    ["ntfy", "https://ntfy.local", "https://ntfy.local/account"],
+    ["anchor", "http://anchor.local:8080", "http://anchor.local:8080/settings"],
+    ["unraid", "http://tower.local", "http://tower.local/Settings/ManagementAccess"],
+    ["coolify", "https://coolify.local", "https://coolify.local/security/api-tokens"],
+    ["immich", "http://immich.local:2283", "http://immich.local:2283/user-settings"],
+    ["tracearr", "http://tracearr.local:7040", "http://tracearr.local:7040/settings"],
+    ["speedtestTracker", "http://speedtest.local", "http://speedtest.local/admin/api-tokens"],
+    ["uptimeKuma", "http://uptime.local:3001", "http://uptime.local:3001/settings/api-keys"],
+  ] as const)("builds a verified credential URL for %s", (kind, baseUrl, expected) => {
+    expect(getIntegrationApiKeyUrl(baseUrl, kind)).toBe(expected);
   });
 
+  it.each(["plex", "piHole", "truenas"] as const)(
+    "returns null when %s has no version-safe credential path",
+    (kind) => {
+      expect(getIntegrationApiKeyUrl("http://localhost", kind)).toBeNull();
+    },
+  );
+
   it("returns null for empty URL", () => {
     expect(getIntegrationApiKeyUrl("", "sonarr")).toBeNull();
   });

packages/definitions/src/test/integration-url-template.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import { getIntegrationDefaultPort } from "../integration";
-import { buildIntegrationUrl } from "../integration-url-template";
+import { buildAppUrl, buildIntegrationUrl } from "../integration-url-template";
 
 describe("buildIntegrationUrl", () => {
   it("builds subdomain URL", () => {
@@ -25,6 +25,31 @@ describe("buildIntegrationUrl", () => {
     expect(buildIntegrationUrl("sonarr", "homelab.local///", "subdomain")).toBe("https://sonarr.homelab.local");
   });
 
+  it("accepts full URLs but ignores their path when suggesting service URLs", () => {
+    expect(buildIntegrationUrl("sonarr", "https://home.example.com/homarr", "hostPort")).toBe(
+      "http://home.example.com:8989",
+    );
+    expect(buildAppUrl("My Service", "http://home.example.com/path", "subdomain")).toBe(
+      "https://my-service.home.example.com",
+    );
+  });
+
+  it("replaces a supplied base port instead of producing a double port", () => {
+    expect(buildIntegrationUrl("sonarr", "https://home.example.com:8443/homarr", "hostPort")).toBe(
+      "http://home.example.com:8989",
+    );
+    expect(buildAppUrl("My Service", "https://home.example.com:8443/homarr", "hostPort")).toBe(
+      "http://home.example.com:8443",
+    );
+  });
+
+  it("formats IPv6 hosts safely in host-port mode", () => {
+    expect(buildIntegrationUrl("sonarr", "https://[2001:db8::1]:8443/homarr", "hostPort")).toBe(
+      "http://[2001:db8::1]:8989",
+    );
+    expect(buildIntegrationUrl("sonarr", "[2001:db8::1]", "subdomain")).toBe("");
+  });
+
   it("returns empty string for empty host", () => {
     expect(buildIntegrationUrl("sonarr", "", "subdomain")).toBe("");
   });
@@ -37,5 +62,11 @@ describe("buildIntegrationUrl", () => {
     expect(getIntegrationDefaultPort("radarr")).toBe(7878);
     expect(getIntegrationDefaultPort("prowlarr")).toBe(9696);
     expect(getIntegrationDefaultPort("jellyfin")).toBe(8096);
+    expect(getIntegrationDefaultPort("technitiumDns")).toBe(5380);
+    expect(getIntegrationDefaultPort("dashDot")).toBe(3001);
+    expect(getIntegrationDefaultPort("gotify")).toBe(80);
+    expect(getIntegrationDefaultPort("peaNut")).toBe(8080);
+    expect(getIntegrationDefaultPort("gluetun")).toBe(8000);
+    expect(getIntegrationDefaultPort("archiveTeamWarrior")).toBe(8001);
   });
 });