@agent-native/toolkit 0.23.1 → 0.198.1

package/src/app/settings/shell/routing.spec.ts

@@ -0,0 +1,290 @@
+import { buildSettingsRoute } from "@agent-native/core/navigation";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { CORE_SETTINGS_PAGES } from "./core-pages.js";
+import { defineSettingsPage, type SettingsPageDefinition } from "./registry.js";
+import {
+  resolveSettingsRoute,
+  resolveSettingsTabValue,
+  settingsPagePath,
+  settingsPathSegments,
+  type SettingsLocation,
+} from "./routing.js";
+
+const Stub = () => null;
+
+/** A template's own tabs, as the bridge turns them into app pages (Mail). */
+const appPage = (id: string, tabId = id): SettingsPageDefinition =>
+  defineSettingsPage({
+    id,
+    group: "app",
+    order: 11,
+    label: id,
+    icon: Stub,
+    component: Stub,
+    legacyTabIds: [tabId],
+  });
+
+const MAIL_PAGES = [
+  ...CORE_SETTINGS_PAGES,
+  appPage("drafting"),
+  appPage("app-automations", "automations"),
+];
+const FORMS_PAGES = [...CORE_SETTINGS_PAGES, appPage("extensions")];
+
+function resolve(
+  pathname: string,
+  hash = "",
+  rest: Partial<SettingsLocation> = {},
+  pages: readonly SettingsPageDefinition[] = CORE_SETTINGS_PAGES,
+) {
+  return resolveSettingsRoute({ pathname, hash, ...rest }, pages);
+}
+
+describe("settings shell routing", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+  });
+
+  it("resolves new page ids and their sub-pages without rewriting them", () => {
+    expect(resolve("/settings/profile")).toEqual({
+      page: "profile",
+      sub: null,
+      anchor: null,
+      legacy: false,
+    });
+    expect(resolve("/settings/integrations/builder")).toMatchObject({
+      page: "integrations",
+      sub: "builder",
+      legacy: false,
+    });
+    expect(resolve("/settings/app/recordings")).toMatchObject({
+      page: "app",
+      sub: "recordings",
+      legacy: false,
+    });
+    // New ids win over a section of the same name.
+    expect(resolve("/settings/auth")).toMatchObject({
+      page: "auth",
+      legacy: false,
+    });
+    expect(resolve("/settings/model", "#limits")).toMatchObject({
+      page: "model",
+      anchor: "limits",
+      legacy: false,
+    });
+  });
+
+  it("leaves bare /settings unresolved so the shell opens its default", () => {
+    expect(resolve("/settings")).toMatchObject({ page: null, sub: null });
+  });
+
+  it("reports an unknown id as named so the shell can redirect it", () => {
+    expect(resolve("/settings/not-a-page")).toEqual({
+      page: "not-a-page",
+      sub: null,
+      anchor: null,
+      legacy: false,
+    });
+  });
+
+  it("strips a workspace mount prefix", () => {
+    vi.stubEnv("VITE_AGENT_NATIVE_WORKSPACE", "1");
+    vi.stubEnv(
+      "VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON",
+      JSON.stringify([{ id: "dispatch", path: "/dispatch" }]),
+    );
+    vi.stubGlobal("window", {
+      location: { pathname: "/dispatch/settings/model" },
+    });
+    expect(settingsPathSegments("/dispatch/settings/model")).toEqual(["model"]);
+    expect(resolve("/dispatch/settings/agent").page).toBe("model");
+  });
+
+  it("builds page paths", () => {
+    expect(settingsPagePath("api-keys")).toBe("/settings/api-keys");
+    expect(settingsPagePath("channels", "slack")).toBe(
+      "/settings/channels/slack",
+    );
+    expect(settingsPagePath("app", null)).toBe("/settings/app");
+  });
+});
+
+// Every link that works today, and where it lands now. `legacy: true` means
+// the shell rewrites the URL to the page's own path.
+describe("legacy settings links", () => {
+  it.each([
+    // Today's tab links, including the e2e paths.
+    ["/settings/general", "", "app", null, null],
+    ["/settings/account", "", "profile", null, null],
+    ["/settings/language", "", "preferences", null, null],
+    ["/settings/agent", "", "model", null, null],
+    ["/settings/providers", "", "model", null, null],
+    ["/settings/agent/resources", "", "files", null, null],
+    ["/settings/agent/resources/files", "", "files", null, null],
+    ["/settings/agent/resources/instructions", "", "instructions", null, null],
+    ["/settings/agent/resources/memory", "", "memory", null, null],
+    ["/settings/agent/resources/learnings", "", "memory", null, "learnings"],
+    ["/settings/agent/resources/skills", "", "skills", null, null],
+    [
+      "/settings/agent/resources/agents",
+      "",
+      "sub-agents",
+      null,
+      "custom-agents",
+    ],
+    ["/settings/agent/automations", "", "automations", null, null],
+    ["/settings/agent/agents", "", "sub-agents", null, "external-agents"],
+    ["/settings/agent/directory", "", "sub-agents", null, "external-agents"],
+    ["/settings/agent/llm", "", "model", null, "llm"],
+    ["/settings/agent/limits", "", "model", null, "limits"],
+    ["/settings/agent/voice", "", "preferences", null, "voice"],
+    ["/settings/organization", "", "org", null, null],
+    ["/settings/team", "", "members", null, null],
+    ["/settings/keys", "", "api-keys", null, null],
+    ["/settings/secrets", "", "api-keys", null, null],
+    ["/settings/connections", "", "integrations", null, null],
+    ["/settings/workspace", "", "infra", null, null],
+    ["/settings/library", "", "creative-context", null, null],
+    ["/settings/changelog", "", "whats-new", null, null],
+    ["/settings/experiments", "", "labs", null, null],
+    ["/settings/labs/lab-meetings", "", "labs", null, "lab-meetings"],
+    // Broken today: a key under Integrations lands on Integrations.
+    [
+      "/settings/integrations/secrets/OPENAI_API_KEY",
+      "",
+      "api-keys",
+      null,
+      "secrets:OPENAI_API_KEY",
+    ],
+    // A row hash on a legacy path survives the rewrite (Clips).
+    ["/settings/general", "#ai-providers", "app", null, "ai-providers"],
+    ["/settings/agent", "#llm", "model", null, "llm"],
+    // Hashes on bare /settings.
+    ["/settings", "#organization", "org", null, null],
+    ["/settings", "#team", "members", null, null],
+    ["/settings", "#agent", "model", null, null],
+    ["/settings", "#agent:resources", "files", null, null],
+    ["/settings", "#llm", "model", null, "llm"],
+    ["/settings", "#agent-limits", "model", null, "limits"],
+    ["/settings", "#voice", "preferences", null, "voice"],
+    ["/settings", "#integrations", "integrations", null, null],
+    ["/settings", "#workspace", "infra", null, null],
+    ["/settings", "#browser", "integrations", "builder", null],
+    ["/settings", "#usage", "usage", null, null],
+    [
+      "/settings",
+      "#secrets:FIGMA_ACCESS_TOKEN",
+      "api-keys",
+      null,
+      "secrets:FIGMA_ACCESS_TOKEN",
+    ],
+    ["/settings", "#labs:lab-meetings", "labs", null, "lab-meetings"],
+  ])("%s%s opens %s", (pathname, hash, page, sub, anchor) => {
+    expect(resolve(pathname, hash)).toEqual({
+      page,
+      sub,
+      anchor,
+      legacy: true,
+    });
+  });
+
+  it("opens the key a built secret route names", () => {
+    const route = buildSettingsRoute(
+      "integrations:secrets:GOOGLE_APPLICATION_CREDENTIALS",
+    );
+    expect(resolve(route)).toEqual({
+      page: "api-keys",
+      sub: null,
+      anchor: "secrets:GOOGLE_APPLICATION_CREDENTIALS",
+      legacy: true,
+    });
+  });
+
+  it("keeps OAuth callbacks and emailed links on their page", () => {
+    expect(
+      resolve("/settings/integrations", "", { search: "?connected=slack" }),
+    ).toMatchObject({ page: "integrations", legacy: false });
+    expect(resolve("/settings/notifications")).toMatchObject({
+      page: "notifications",
+      legacy: false,
+    });
+  });
+
+  it("sends /extensions to the app's Extensions page, else its General page", () => {
+    expect(resolve("/settings/extensions", "", {}, FORMS_PAGES)).toMatchObject({
+      page: "extensions",
+      legacy: false,
+    });
+    expect(resolve("/settings/extensions")).toMatchObject({
+      page: "app",
+      legacy: true,
+    });
+  });
+
+  it("reads ?section= as the template's own tab id", () => {
+    const section = (value: string) =>
+      resolve("/settings", "", { search: `?section=${value}` }, MAIL_PAGES);
+    expect(section("drafting")).toMatchObject({
+      page: "drafting",
+      legacy: true,
+    });
+    // Mail's inbox rules, not the core Automations page.
+    expect(section("automations")).toMatchObject({ page: "app-automations" });
+    // Broken today: Mail's /team sends ?section=team, which has no tab.
+    expect(section("team")).toMatchObject({ page: "members" });
+    expect(section("general")).toMatchObject({ page: "app" });
+    expect(section("agent")).toMatchObject({ page: "model" });
+  });
+
+  it("routes app areas under the app's General page", () => {
+    expect(
+      resolveSettingsTabValue("recordings", CORE_SETTINGS_PAGES, [
+        "recordings",
+      ]),
+    ).toMatchObject({ page: "app", sub: "recordings" });
+    // Today's tab path for an area (Analytics' Alerts tab).
+    expect(
+      resolveSettingsRoute(
+        { pathname: "/settings/alerts", hash: "#alert-rules" },
+        CORE_SETTINGS_PAGES,
+        { appAreaIds: ["alerts"] },
+      ),
+    ).toMatchObject({
+      page: "app",
+      sub: "alerts",
+      anchor: "alert-rules",
+      legacy: true,
+    });
+    // A core page id stays the core page.
+    expect(
+      resolveSettingsRoute(
+        { pathname: "/settings/usage", hash: "" },
+        CORE_SETTINGS_PAGES,
+        { appAreaIds: ["usage"] },
+      ),
+    ).toMatchObject({ page: "usage", legacy: false });
+  });
+
+  it("prefers the agent panel's section over the hash it navigated to", () => {
+    // The panel sends `secrets` to #integrations for today's Settings.
+    expect(
+      resolve("/settings", "#integrations", { section: "secrets" }),
+    ).toMatchObject({ page: "api-keys", legacy: true });
+    expect(
+      resolve("/settings", "#workspace", { section: "workspace-settings" }),
+    ).toMatchObject({ page: "org" });
+    expect(
+      resolve("/settings", "#secrets:OPENAI_API_KEY", { section: "secrets" }),
+    ).toMatchObject({ page: "api-keys", anchor: "secrets:OPENAI_API_KEY" });
+  });
+
+  it("opens the template's chosen tab on a bare /settings", () => {
+    expect(
+      resolveSettingsRoute({ pathname: "/settings", hash: "" }, MAIL_PAGES, {
+        tabValue: "drafting",
+      }),
+    ).toMatchObject({ page: "drafting", legacy: true });
+  });
+});

package/src/app/settings/shell/routing.ts

@@ -0,0 +1,276 @@
+import {
+  appMountedPath,
+  appMountPath,
+} from "@agent-native/core/client/api-path";
+import {
+  buildSettingsRoute,
+  STANDARD_APP_ROUTES,
+} from "@agent-native/core/navigation";
+import {
+  isCoreSettingsPageId,
+  resolveLegacySettingsId,
+  resolveSettingsIdPattern,
+  resolveSettingsSectionRedirect,
+  type SettingsRedirect,
+} from "@agent-native/core/navigation/settings-redirects";
+
+import type { SettingsPageDefinition } from "./registry.js";
+
+export interface SettingsLocation {
+  pathname: string;
+  hash: string;
+  /** The query string. `?section=` names a template tab (Mail, Brain). */
+  search?: string;
+  /** An `agent-panel:open-settings` section carried in history state. */
+  section?: string | null;
+}
+
+export interface SettingsRoute {
+  page: string | null;
+  sub: string | null;
+}
+
+export interface ResolvedSettingsRoute extends SettingsRoute {
+  /** In-page target to scroll to: a row or group id, a section id, or `secrets:KEY`. */
+  anchor: string | null;
+  /**
+   * The URL named the page through a legacy form, so the shell replaces it
+   * with the page's own path (keeping the query).
+   */
+  legacy: boolean;
+}
+
+export interface ResolveSettingsRouteOptions {
+  /** Tabs on the app's General page, routed `/settings/app/<id>`. */
+  appAreaIds?: readonly string[];
+  /**
+   * The tab a controlled template chose. A bare `/settings` opens it, which
+   * covers the moment between a template stripping `?section=` from the URL
+   * and the shell navigating to the page it named.
+   */
+  tabValue?: string | null;
+}
+
+/**
+ * `history.state` key for the section an `agent-panel:open-settings` request
+ * named. Today's Settings reads only the hash it navigates to; the shell reads
+ * this first because that hash can't tell API keys from Integrations.
+ */
+export const SETTINGS_SECTION_STATE_KEY = "agentNativeSettingsSection";
+
+const SETTINGS_PREFIX = STANDARD_APP_ROUTES.settings;
+
+const NO_ROUTE: ResolvedSettingsRoute = {
+  page: null,
+  sub: null,
+  anchor: null,
+  legacy: false,
+};
+
+/** Strips a workspace mount (`/dispatch/settings/…` → `/settings/…`). */
+export function settingsLocalPathname(pathname: string): string {
+  const mountPath = appMountPath(SETTINGS_PREFIX);
+  if (
+    mountPath &&
+    (pathname === mountPath || pathname.startsWith(`${mountPath}/`))
+  ) {
+    return pathname.slice(mountPath.length) || "/";
+  }
+  return pathname;
+}
+
+export function isSettingsPathname(pathname: string): boolean {
+  const local = settingsLocalPathname(pathname);
+  return local === SETTINGS_PREFIX || local.startsWith(`${SETTINGS_PREFIX}/`);
+}
+
+function decodeSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    // coercion-ok: a malformed external segment still routes by its raw text.
+    return segment;
+  }
+}
+
+export function settingsPathSegments(pathname: string): string[] {
+  const local = settingsLocalPathname(pathname);
+  if (!local.startsWith(`${SETTINGS_PREFIX}/`)) return [];
+  return local
+    .slice(SETTINGS_PREFIX.length + 1)
+    .split("/")
+    .filter(Boolean)
+    .map(decodeSegment);
+}
+
+/** `/settings/:page` or `/settings/:page/:sub`. */
+export function settingsPagePath(page: string, sub?: string | null): string {
+  return buildSettingsRoute(page, sub ?? null);
+}
+
+/** The browser URL for a page, keeping a workspace mount prefix. */
+export function settingsPageHref(page: string, sub?: string | null): string {
+  return appMountedPath(settingsPagePath(page, sub), SETTINGS_PREFIX);
+}
+
+/** The `?section=` a Mail or Brain deep link carries, if any. */
+export function settingsSectionParam(search: string | undefined): string {
+  if (!search) return "";
+  return new URLSearchParams(search).get("section")?.trim() ?? "";
+}
+
+function redirectRoute(
+  redirect: SettingsRedirect,
+  pages: readonly SettingsPageDefinition[],
+  fallbackAnchor: string | null,
+): ResolvedSettingsRoute {
+  const exists = (id: string) => pages.some((page) => page.id === id);
+  const page =
+    !exists(redirect.page) &&
+    redirect.fallbackPage &&
+    exists(redirect.fallbackPage)
+      ? redirect.fallbackPage
+      : redirect.page;
+  return {
+    page,
+    sub: page === redirect.page ? (redirect.sub ?? null) : null,
+    anchor: redirect.anchor ?? fallbackAnchor,
+    legacy: true,
+  };
+}
+
+/** Pages a template contributed (its own tabs), which own their tab ids. */
+function isAppPage(page: SettingsPageDefinition): boolean {
+  return !isCoreSettingsPageId(page.id);
+}
+
+function pageForTabIds(
+  ids: readonly string[],
+  pages: readonly SettingsPageDefinition[],
+): SettingsPageDefinition | undefined {
+  for (let length = ids.length; length > 0; length -= 1) {
+    const id = ids.slice(0, length).join(":");
+    const page = pages.find((candidate) =>
+      candidate.legacyTabIds?.includes(id),
+    );
+    if (page) return page;
+  }
+  return undefined;
+}
+
+/**
+ * The page a template's tab id opens. The template's own tabs win, because
+ * its id space is its own: Mail's inbox `automations` tab is not the core
+ * Automations page.
+ */
+export function resolveSettingsTabValue(
+  value: string,
+  pages: readonly SettingsPageDefinition[],
+  appAreaIds: readonly string[] = [],
+): ResolvedSettingsRoute {
+  const tab = value.trim();
+  if (!tab) return NO_ROUTE;
+  const appPage = pages.find(
+    (page) =>
+      isAppPage(page) && (page.id === tab || page.legacyTabIds?.includes(tab)),
+  );
+  if (appPage) {
+    return { page: appPage.id, sub: null, anchor: null, legacy: true };
+  }
+  if (appAreaIds.includes(tab)) {
+    return { page: "app", sub: tab, anchor: null, legacy: true };
+  }
+  const redirect = resolveLegacySettingsId(tab, "tab");
+  if (redirect) return redirectRoute(redirect, pages, null);
+  const page =
+    pages.find((candidate) => candidate.id === tab) ??
+    pageForTabIds(tab.split(":"), pages);
+  return page
+    ? { page: page.id, sub: null, anchor: null, legacy: true }
+    : NO_ROUTE;
+}
+
+/**
+ * Which page a Settings URL names, through the legacy redirect table
+ * (`settings-redirects.ts`) when it isn't a page's own path. `legacy` routes
+ * are rewritten by the shell; an unknown id comes back as named so the shell
+ * can send it to Profile.
+ */
+export function resolveSettingsRoute(
+  location: SettingsLocation,
+  pages: readonly SettingsPageDefinition[],
+  options: ResolveSettingsRouteOptions = {},
+): ResolvedSettingsRoute {
+  const segments = settingsPathSegments(location.pathname);
+  const hash = decodeSegment(location.hash.replace(/^#/, ""));
+  if (segments.length > 0) {
+    const joined = segments.join(":");
+    const pageId = segments[0]!;
+    if (pages.some((page) => page.id === pageId)) {
+      const pattern = segments.length > 1 && resolveSettingsIdPattern(joined);
+      if (pattern) return redirectRoute(pattern, pages, hash || null);
+      return {
+        page: pageId,
+        sub: segments[1] ?? null,
+        anchor: hash || null,
+        legacy: segments.length > 2,
+      };
+    }
+    // Today's tab link to an area that moved onto the app's General page
+    // (`/settings/alerts`). Checked before the redirect table, like
+    // `resolveSettingsTabValue`, because the area id is the template's own.
+    if (options.appAreaIds?.includes(pageId)) {
+      return { page: "app", sub: pageId, anchor: hash || null, legacy: true };
+    }
+    const redirect = resolveLegacySettingsId(joined, "tab");
+    if (redirect) return redirectRoute(redirect, pages, hash || null);
+    const tabPage = pageForTabIds(segments, pages);
+    if (tabPage) {
+      return {
+        page: tabPage.id,
+        sub: null,
+        anchor: hash || null,
+        legacy: true,
+      };
+    }
+    return {
+      page: pageId,
+      sub: segments[1] ?? null,
+      anchor: null,
+      legacy: false,
+    };
+  }
+
+  if (location.section) {
+    return redirectRoute(
+      resolveSettingsSectionRedirect(location.section, hash),
+      pages,
+      null,
+    );
+  }
+  if (hash) {
+    const redirect = resolveLegacySettingsId(hash, "section");
+    if (redirect) return redirectRoute(redirect, pages, null);
+    const page =
+      pages.find((candidate) => candidate.id === hash) ??
+      pageForTabIds(hash.split(":"), pages);
+    if (page) return { page: page.id, sub: null, anchor: null, legacy: true };
+    const owner = pages.find((candidate) =>
+      candidate.searchEntries?.some(
+        (entry) => entry.anchor === hash || entry.id === hash,
+      ),
+    );
+    if (owner) {
+      return { page: owner.id, sub: null, anchor: hash, legacy: true };
+    }
+  }
+  const section = settingsSectionParam(location.search);
+  if (section) {
+    const route = resolveSettingsTabValue(section, pages, options.appAreaIds);
+    if (route.page) return route;
+  }
+  if (options.tabValue) {
+    return resolveSettingsTabValue(options.tabValue, pages, options.appAreaIds);
+  }
+  return NO_ROUTE;
+}

package/src/app/settings/shell/search.spec.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+
+import { defineSettingsPage } from "./registry.js";
+import { buildSettingsSearchIndex, searchSettings } from "./search.js";
+
+const Stub = () => null;
+
+const model = defineSettingsPage({
+  id: "model",
+  group: "agent",
+  order: 10,
+  labelKey: "page.model",
+  icon: Stub,
+  component: Stub,
+  keywords: "llm provider",
+});
+
+const index = buildSettingsSearchIndex(
+  [
+    {
+      page: model,
+      label: "Model",
+      groupLabel: "Agent",
+      entries: [
+        {
+          id: "max-iterations",
+          labelKey: "row.maxIterations",
+          keywords: "limits loop",
+          anchor: "limits",
+        },
+      ],
+    },
+  ],
+  (key) => (key === "row.maxIterations" ? "Max iterations" : key),
+);
+
+describe("settings shell search", () => {
+  it("finds pages by label and keywords", () => {
+    expect(searchSettings(index, "llm")[0]).toMatchObject({
+      label: "Model",
+      where: "Agent",
+      page: "model",
+    });
+  });
+
+  it("finds rows and says where they live", () => {
+    expect(searchSettings(index, "max iter")[0]).toMatchObject({
+      label: "Max iterations",
+      where: "Agent › Model",
+      page: "model",
+      anchor: "limits",
+    });
+  });
+
+  it("skips a row that only repeats its page's name", () => {
+    const withDuplicate = buildSettingsSearchIndex(
+      [
+        {
+          page: model,
+          label: "Model",
+          groupLabel: "Agent",
+          entries: [{ id: "section:llm", label: "Model", anchor: "llm" }],
+        },
+      ],
+      (key) => key,
+    );
+    expect(searchSettings(withDuplicate, "model")).toHaveLength(1);
+  });
+
+  it("keeps the page's own row when a bridged entry repeats its name", () => {
+    const withBridged = buildSettingsSearchIndex(
+      [
+        {
+          page: model,
+          label: "Model",
+          groupLabel: "Agent",
+          entries: [
+            { id: "limits", label: "Limits", anchor: "limits" },
+            { id: "section:limits", label: "Limits", anchor: "old-limits" },
+          ],
+        },
+      ],
+      (key) => key,
+    );
+    expect(searchSettings(withBridged, "limits")).toMatchObject([
+      { label: "Limits", anchor: "limits" },
+    ]);
+  });
+
+  it("returns nothing for an empty query", () => {
+    expect(searchSettings(index, "   ")).toEqual([]);
+  });
+});