@cat-factory/app 0.198.1 → 0.199.0

package/app/modular/external-tools.spec.ts

@@ -0,0 +1,281 @@
+import { describe, expect, it, vi } from 'vitest'
+import { missingI18nKeys } from '../../test/i18nKeys'
+import {
+  EXTERNAL_TOOL_UNAVAILABLE_KEYS,
+  filterExternalTools,
+  projectExternalTools,
+  resolveExternalToolUrl,
+  type ExternalToolContext,
+  type ExternalToolContribution,
+} from './external-tools'
+import type { NavGates } from './nav-contributions'
+
+const CONTEXT: ExternalToolContext = {
+  userId: 'usr_1',
+  userEmail: 'ada@example.com',
+  workspaceId: 'ws_1',
+  workspaceName: 'Zork',
+  metadata: { gameId: 'zork' },
+}
+
+const MAP_EDITOR: ExternalToolContribution = {
+  id: 'acme:map-editor',
+  title: 'Map editor',
+  icon: 'i-lucide-map',
+  requiredMetadata: ['gameId'],
+  url: (ctx) =>
+    `https://maps.acme.dev/edit?game=${ctx.metadata.gameId}&ws=${ctx.workspaceId}&user=${ctx.userId ?? ''}`,
+}
+
+const GATES: NavGates = {
+  canWriteBoard: true,
+  canManageIntegrations: true,
+  canManageSettings: true,
+  githubAvailable: true,
+  libraryAvailable: true,
+  infrastructureAvailable: true,
+  accountsEnabled: true,
+  isAccountAdmin: true,
+  advancedMode: true,
+  boardHasService: true,
+  boardHasTask: true,
+  boardHasRun: true,
+  boardHasOpenDecision: true,
+  boardHasPendingApproval: true,
+  boardHasFinishedRun: true,
+}
+
+describe('resolveExternalToolUrl', () => {
+  it('folds the invocation context into the resolved URL', () => {
+    // The whole point of a resolver over a static link: the tool opens on the right game,
+    // for the right workspace, as the right user.
+    expect(resolveExternalToolUrl(MAP_EDITOR, CONTEXT)).toEqual({
+      ok: true,
+      url: 'https://maps.acme.dev/edit?game=zork&ws=ws_1&user=usr_1',
+    })
+  })
+
+  it('accepts a static URL with no resolver', () => {
+    const tool = { ...MAP_EDITOR, requiredMetadata: undefined, url: 'https://acme.dev/console' }
+    expect(resolveExternalToolUrl(tool, CONTEXT)).toMatchObject({ ok: true })
+  })
+
+  it('names the unfilled metadata fields instead of opening a half-scoped tool', () => {
+    const empty = { ...CONTEXT, metadata: {} }
+
+    // `missing-metadata` + the key list is what lets the UI say "fill in gameId in workspace
+    // settings" — a bare "unavailable" would send the operator to the deployment's admins.
+    expect(resolveExternalToolUrl(MAP_EDITOR, empty)).toEqual({
+      ok: false,
+      reason: 'missing-metadata',
+      missing: ['gameId'],
+    })
+  })
+
+  it('treats a required field stored as blank as missing', () => {
+    // The store drops a cleared value, but a bag that arrived from anywhere else must not
+    // resolve to `?game=`.
+    const blank = { ...CONTEXT, metadata: { gameId: '' } }
+    expect(resolveExternalToolUrl(MAP_EDITOR, blank)).toMatchObject({ reason: 'missing-metadata' })
+  })
+
+  it('reports a declining resolver separately from an unconfigured workspace', () => {
+    const tool: ExternalToolContribution = { ...MAP_EDITOR, url: () => null }
+
+    // Two different fixes: nobody to nag about settings here, this is the deployment's own
+    // condition not being met.
+    expect(resolveExternalToolUrl(tool, CONTEXT)).toEqual({
+      ok: false,
+      reason: 'unresolved',
+      missing: [],
+    })
+  })
+
+  it('reports a resolver that THREW separately, carrying the cause', () => {
+    const boom = new TypeError("Cannot read properties of undefined (reading 'split')")
+    const tool: ExternalToolContribution = {
+      ...MAP_EDITOR,
+      requiredMetadata: undefined,
+      url: () => {
+        throw boom
+      },
+    }
+
+    // Distinct from `unresolved`: declining is a resolver working as written, throwing is a
+    // bug in it. The cause rides along so the caller can put a stack in the console — the
+    // deployment author who must fix it is not the person reading the toast.
+    expect(resolveExternalToolUrl(tool, CONTEXT)).toEqual({
+      ok: false,
+      reason: 'resolver-failed',
+      missing: [],
+      cause: boom,
+    })
+  })
+
+  it('treats a required field named after an Object member as missing', () => {
+    // `constructor` / `toString` / `valueOf` all pass the key pattern (only a leading `_` is
+    // barred, which is what keeps `__proto__` out). On a plain object an unfilled one reads as
+    // an INHERITED function, i.e. truthy — so a naive `metadata[key]` check would conclude the
+    // field is set and hand the resolver `Object` itself.
+    const tool: ExternalToolContribution = { ...MAP_EDITOR, requiredMetadata: ['constructor'] }
+    expect(resolveExternalToolUrl(tool, { ...CONTEXT, metadata: {} })).toEqual({
+      ok: false,
+      reason: 'missing-metadata',
+      missing: ['constructor'],
+    })
+  })
+
+  it.each([
+    // The security-relevant one: the resolved string is handed to `window.open`, so a
+    // `javascript:` URL would execute in the SPA's own origin.
+    'javascript:alert(1)',
+    'data:text/html,<script>alert(1)</script>',
+    'file:///etc/passwd',
+    '/relative/path',
+    'not a url',
+  ])('refuses %s rather than handing it to the browser', (url) => {
+    const tool: ExternalToolContribution = { ...MAP_EDITOR, url: () => url }
+    expect(resolveExternalToolUrl(tool, CONTEXT)).toMatchObject({ reason: 'unsafe-url' })
+  })
+})
+
+describe('projectExternalTools', () => {
+  const handlers = () => ({ open: vi.fn(), onUnavailable: vi.fn() })
+
+  it('projects a tool onto a nav contribution in the External tools section', () => {
+    const [item] = projectExternalTools([MAP_EDITOR], CONTEXT, handlers())
+
+    expect(item?.contribution).toMatchObject({
+      id: 'acme:map-editor',
+      // Deployment DATA rides `label`, so the shells render it verbatim instead of through `t()`.
+      label: 'Map editor',
+      icon: 'i-lucide-map',
+      sidebar: { group: 'externalTools' },
+      command: { group: 'externalTools' },
+      testId: 'nav-external-tool-acme:map-editor',
+    })
+    expect(item?.contribution.surfaces).toEqual(['sidebar', 'command'])
+  })
+
+  it('orders by declared order, keeping registration order within a tie', () => {
+    const tool = (id: string, order?: number): ExternalToolContribution => ({
+      id,
+      title: id,
+      icon: 'i-lucide-link',
+      url: 'https://acme.dev',
+      ...(order === undefined ? {} : { order }),
+    })
+    const items = projectExternalTools(
+      [tool('c', 20), tool('a'), tool('b'), tool('d', 10)],
+      CONTEXT,
+      handlers(),
+    )
+
+    expect(items.map((i) => i.tool.id)).toEqual(['a', 'b', 'd', 'c'])
+    expect(items.map((i) => i.contribution.sidebar?.order)).toEqual([0, 1, 2, 3])
+  })
+
+  it('opens the resolved URL on click', () => {
+    const h = handlers()
+    const [item] = projectExternalTools([MAP_EDITOR], CONTEXT, h)
+
+    item?.contribution.run?.()
+
+    expect(h.open).toHaveBeenCalledWith(
+      'https://maps.acme.dev/edit?game=zork&ws=ws_1&user=usr_1',
+      MAP_EDITOR,
+    )
+    expect(h.onUnavailable).not.toHaveBeenCalled()
+  })
+
+  it('keeps an unresolvable tool listed and reports why on click', () => {
+    const h = handlers()
+    const [item] = projectExternalTools([MAP_EDITOR], { ...CONTEXT, metadata: {} }, h)
+
+    // Listed, not hidden: hiding it makes "nobody filled in gameId" look exactly like
+    // "this deployment never registered a map editor", and the person who can fix it is
+    // the one reading the sidebar.
+    expect(item?.resolution).toMatchObject({ ok: false, reason: 'missing-metadata' })
+    item?.contribution.run?.()
+    expect(h.open).not.toHaveBeenCalled()
+    expect(h.onUnavailable).toHaveBeenCalledWith(
+      { ok: false, reason: 'missing-metadata', missing: ['gameId'] },
+      MAP_EDITOR,
+    )
+  })
+
+  it('survives a throwing resolver instead of taking the nav catalog down with it', () => {
+    const h = handlers()
+    const exploding: ExternalToolContribution = {
+      id: 'acme:broken',
+      title: 'Broken',
+      icon: 'i-lucide-bug',
+      url: () => {
+        throw new Error('boom')
+      },
+    }
+
+    // This projection runs inside the `externalToolItems` computed, which feeds the sidebar,
+    // the command palette AND the board toolbar. A registration mistake in a deployment's own
+    // code must cost that one item — not every nav shell in the app.
+    const items = projectExternalTools([exploding, MAP_EDITOR], CONTEXT, h)
+
+    expect(items.map((i) => i.tool.id)).toEqual(['acme:broken', 'acme:map-editor'])
+    expect(items[0]?.resolution).toMatchObject({ ok: false, reason: 'resolver-failed' })
+    expect(items[1]?.resolution.ok).toBe(true)
+
+    // Clicking the broken one reports, and still doesn't throw at the shell.
+    expect(() => items[0]?.contribution.run?.()).not.toThrow()
+    expect(h.open).not.toHaveBeenCalled()
+    expect(h.onUnavailable).toHaveBeenCalledWith(
+      expect.objectContaining({ reason: 'resolver-failed' }),
+      exploding,
+    )
+  })
+
+  it('re-resolves at click time, so a value filled in meanwhile is picked up', () => {
+    const h = handlers()
+    const metadata: Record<string, string> = {}
+    // The composable passes a context built from reactive stores; a resolution captured at
+    // projection time would keep reporting a fix that has already happened.
+    const [item] = projectExternalTools([MAP_EDITOR], { ...CONTEXT, metadata }, h)
+    expect(item?.resolution.ok).toBe(false)
+
+    metadata.gameId = 'myst'
+    item?.contribution.run?.()
+
+    expect(h.open).toHaveBeenCalledWith(expect.stringContaining('game=myst'), MAP_EDITOR)
+  })
+})
+
+describe('filterExternalTools', () => {
+  const tools: ExternalToolContribution[] = [
+    { id: 'a', title: 'A', icon: 'i', url: 'https://a.dev' },
+    { id: 'b', title: 'B', icon: 'i', url: 'https://b.dev', gate: (g) => g.canManageIntegrations },
+    { id: 'c', title: 'C', icon: 'i', url: 'https://c.dev', advanced: true },
+  ]
+
+  it('applies the RBAC gate and the interface tier independently', () => {
+    expect(filterExternalTools(tools, GATES).map((t) => t.id)).toEqual(['a', 'b', 'c'])
+    expect(
+      filterExternalTools(tools, { ...GATES, canManageIntegrations: false }).map((t) => t.id),
+    ).toEqual(['a', 'c'])
+    expect(filterExternalTools(tools, { ...GATES, advancedMode: false }).map((t) => t.id)).toEqual([
+      'a',
+      'b',
+    ])
+  })
+
+  it('passes everything through with no gates service wired (dev-open parity)', () => {
+    expect(filterExternalTools(tools, undefined).map((t) => t.id)).toEqual(['a', 'b', 'c'])
+  })
+})
+
+describe('EXTERNAL_TOOL_UNAVAILABLE_KEYS', () => {
+  it('names copy that exists for every reason', () => {
+    // The exhaustive `Record` proves each reason HAS an entry; only this proves the entry still
+    // names a live key. Neither typed message keys nor `i18n:check` can see a lookup table, so a
+    // deleted key would otherwise read as a clean removal and render its own path in a toast.
+    expect(missingI18nKeys(Object.values(EXTERNAL_TOOL_UNAVAILABLE_KEYS))).toEqual([])
+  })
+})

package/app/modular/external-tools.ts

@@ -0,0 +1,265 @@
+import { metadataValue } from './workspace-metadata'
+import type { NavContribution, NavGates } from './nav-contributions'
+
+/**
+ * EXTERNAL TOOLS — a deployment's own web applications, registered programmatically and
+ * listed in their own "External tools" sidebar section (and in the command palette).
+ * Clicking one opens it in a separate browser page.
+ *
+ * The point is not the link; it is the CONTEXT that rides on it. A deployment's map editor,
+ * asset pipeline or admin console is almost always already scoped to something cat-factory
+ * knows — the signed-in user, the open workspace, or a workspace-specific identifier the
+ * deployment declared as a custom metadata field ("this board is game `zork`"). So a tool
+ * declares a {@link ExternalToolUrlResolver} — a pure function from the invocation context to
+ * a URL — instead of a static link, and lands the user on the right state instead of the
+ * tool's front door.
+ *
+ * Everything here is PURE (no Vue, no stores): the composable that renders these
+ * (`useNavContributions`) builds the {@link ExternalToolContext} from the auth/workspace/
+ * settings stores and hands it in, so the resolution rules stay unit-testable and the click
+ * behaviour stays in one place.
+ */
+
+/** What a resolver may read about the invocation. Every field is data the SPA already holds. */
+export interface ExternalToolContext {
+  /** The signed-in user's id, or null when the deployment runs with auth disabled. */
+  userId: string | null
+  /** The signed-in user's email, or null (auth disabled, or a user record without one). */
+  userEmail: string | null
+  /** The open workspace's id. */
+  workspaceId: string
+  /** The open workspace's display name. */
+  workspaceName: string
+  /**
+   * The workspace's custom metadata values, keyed by the field keys the deployment declared
+   * (see {@link WorkspaceMetadataFieldDefinition}). A field nobody has filled in is ABSENT,
+   * never `''` — which is what lets {@link resolveExternalToolUrl} report a missing value as
+   * a missing value instead of building a URL with an empty parameter. The bag is hung on a
+   * null prototype (`toMetadataBag`), so a plain `ctx.metadata.gameId` on an unfilled field
+   * reads `undefined` even where the key names something on `Object.prototype`.
+   *
+   * TREAT EVERY VALUE AS UNTRUSTED INPUT. A workspace admin types these in, so a value is
+   * operator-supplied text that happens to be bounded — not a constant your deployment chose.
+   * Interpolate one into a query parameter (`url.searchParams.set(...)`) or an
+   * `encodeURIComponent`'d path segment, as the `acme:map-editor` example does. Never build the
+   * ORIGIN from a value: `` `https://${ctx.metadata.region}.acme.dev` `` with `region` set to
+   * `evil.com/x?a=` resolves to a URL on someone else's host, and the `http(s)` allow-list below
+   * cannot tell that apart from the link you meant.
+   */
+  metadata: Readonly<Record<string, string>>
+}
+
+/**
+ * Build the tool's URL from the invocation context. Returning `null` (or an empty string)
+ * means "not resolvable right now" — the tool stays listed and says so when clicked, rather
+ * than opening something wrong.
+ */
+export type ExternalToolUrlResolver = (context: ExternalToolContext) => string | null
+
+/** One registered external tool. */
+export interface ExternalToolContribution {
+  /** Namespaced id (`<ns>:<name>`), like every other consumer contribution. */
+  id: string
+  /** Display name. Literal copy, not an i18n key: a tool's name is deployment DATA (the same
+   *  class as a custom agent kind's `presentation.label`), and the deployment ships whatever
+   *  locales it needs in its own catalog. */
+  title: string
+  /** One line of "what is this and why would I click it", shown as the item's tooltip. */
+  description?: string
+  /** Icon name (the same `i-lucide-*` vocabulary as every nav item). */
+  icon: string
+  /**
+   * Where the tool lives: a fixed URL, or a resolver that folds the invocation context in.
+   * Must resolve to an `http(s)` URL — anything else is refused (see
+   * {@link resolveExternalToolUrl}).
+   */
+  url: string | ExternalToolUrlResolver
+  /**
+   * Metadata field keys the resolver needs. Checked BEFORE the resolver runs, so an
+   * unconfigured workspace gets a message naming the fields to fill in rather than the
+   * generic "couldn't work out where this goes" a null return can only mean. Declaring them
+   * is what turns "the tool is broken" into "somebody has to fill in `gameId`".
+   */
+  requiredMetadata?: readonly string[]
+  /** Sidebar/palette order within the External tools section. Defaults to 0. */
+  order?: number
+  /** Reactive RBAC/availability predicate, exactly as on a {@link NavContribution}. */
+  gate?: (gates: NavGates) => boolean
+  /** Show only in advanced interface mode. */
+  advanced?: boolean
+  /** Stable selector for e2e. Defaults to `nav-external-tool-<id>`. */
+  testId?: string
+}
+
+/** Why a tool's URL could not be produced. Each names a DIFFERENT fix. */
+export type ExternalToolUnavailableReason =
+  /** The workspace has not filled in metadata fields the tool declared as required. */
+  | 'missing-metadata'
+  /** The resolver ran and declined to produce a URL (its own conditions weren't met). */
+  | 'unresolved'
+  /** The resolver THREW. A bug in the registration, distinct from it declining on purpose. */
+  | 'resolver-failed'
+  /** A URL was produced but isn't an `http(s)` link we may hand to the browser. */
+  | 'unsafe-url'
+
+/** A resolved tool URL, or the reason there isn't one. */
+export type ExternalToolResolution =
+  | { ok: true; url: string }
+  | {
+      ok: false
+      reason: ExternalToolUnavailableReason
+      missing: readonly string[]
+      /** What the resolver threw, on `resolver-failed`. The caller logs it; nothing else reads it. */
+      cause?: unknown
+    }
+
+/**
+ * Reason → the copy that says what to do about it, owned HERE rather than by the composable
+ * that renders it: the reasons are this module's vocabulary, and keeping the map beside them is
+ * what lets `external-tools.spec.ts` assert the keys resolve.
+ *
+ * An exhaustive `Record` over the union is the drift guard in one direction — a new reason fails
+ * to compile until it has copy. It cannot check the other direction, because the typed-message-key
+ * check only sees a key written literally at a `t()` call and these are looked up at runtime; the
+ * spec's `hasI18nKey` assertion over these values is what closes that half (see `test/i18nKeys.ts`).
+ */
+export const EXTERNAL_TOOL_UNAVAILABLE_KEYS: Record<ExternalToolUnavailableReason, string> = {
+  'missing-metadata': 'externalTools.unavailable.missingMetadata',
+  unresolved: 'externalTools.unavailable.unresolved',
+  'resolver-failed': 'externalTools.unavailable.resolverFailed',
+  'unsafe-url': 'externalTools.unavailable.unsafeUrl',
+}
+
+/**
+ * Resolve a tool's URL for one invocation. TOTAL: it reports a refusal for every way a
+ * registration can fail, and never throws.
+ *
+ * Four refusals, deliberately distinct (the "distinguish the causes that need different
+ * fixes" rule): a workspace that hasn't filled in `gameId` needs someone to open workspace
+ * settings; a resolver that declined needs the deployment's own attention; a resolver that
+ * THREW is a bug in code the host doesn't own; a non-`http(s)` URL is a bug in the
+ * registration. Collapsing them into one "unavailable" would send every one of those to the
+ * wrong person.
+ *
+ * Totality is the load-bearing part, not politeness about third-party bugs. This runs inside
+ * the `externalToolItems` computed, which is concatenated into the nav catalog that the
+ * sidebar, the command palette AND the board toolbar all render from — so a resolver throwing
+ * (`ctx.metadata.gameId.split('-')` on a field it forgot to declare as required) would take
+ * out all three shells at once, not the one item that is broken. A deployment's registration
+ * mistake must cost that registration and nothing else.
+ *
+ * The scheme check is load-bearing in the other sense: the resolved string is handed to
+ * `window.open`, so a `javascript:` URL from a mis-built resolver would execute in the SPA's
+ * own origin. An allow-list of `http:`/`https:` is the boundary — a relative or malformed
+ * URL fails the `URL` parse and lands in the same refusal.
+ */
+export function resolveExternalToolUrl(
+  tool: ExternalToolContribution,
+  context: ExternalToolContext,
+): ExternalToolResolution {
+  const missing = (tool.requiredMetadata ?? []).filter(
+    (key) => !metadataValue(context.metadata, key),
+  )
+  if (missing.length > 0) return { ok: false, reason: 'missing-metadata', missing }
+
+  let raw: string | null
+  try {
+    raw = typeof tool.url === 'function' ? tool.url(context) : tool.url
+  } catch (cause) {
+    // Reported, never swallowed: `cause` rides the refusal so the caller can log what threw.
+    // A deployment author is the only person who can fix this, and they need the stack.
+    return { ok: false, reason: 'resolver-failed', missing: [], cause }
+  }
+  if (!raw) return { ok: false, reason: 'unresolved', missing: [] }
+
+  let parsed: URL
+  try {
+    parsed = new URL(raw)
+  } catch {
+    return { ok: false, reason: 'unsafe-url', missing: [] }
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    return { ok: false, reason: 'unsafe-url', missing: [] }
+  }
+  return { ok: true, url: parsed.toString() }
+}
+
+/** A tool projected onto the nav catalog, with its resolution already computed. */
+export interface ExternalToolNavItem {
+  tool: ExternalToolContribution
+  resolution: ExternalToolResolution
+  contribution: NavContribution
+}
+
+/** The sidebar/palette order a tool with no `order` takes. */
+const DEFAULT_ORDER = 0
+
+/**
+ * Project registered tools onto {@link NavContribution}s in the `externalTools` section, so
+ * the three nav shells render them exactly like every other destination — one catalog, one
+ * renderer.
+ *
+ * Unresolvable tools are KEPT in the list, carrying their refusal. Hiding them would make a
+ * workspace that hasn't filled in `gameId` indistinguishable from a deployment that never
+ * registered the tool, and the person who can fix it is the one looking at the sidebar. The
+ * caller supplies `onUnavailable`, which is what turns a click into a message naming the fix.
+ */
+export function projectExternalTools(
+  tools: readonly ExternalToolContribution[],
+  context: ExternalToolContext,
+  handlers: {
+    open: (url: string, tool: ExternalToolContribution) => void
+    onUnavailable: (
+      resolution: Extract<ExternalToolResolution, { ok: false }>,
+      tool: ExternalToolContribution,
+    ) => void
+  },
+): ExternalToolNavItem[] {
+  return [...tools]
+    .sort((a, b) => (a.order ?? DEFAULT_ORDER) - (b.order ?? DEFAULT_ORDER))
+    .map((tool, index) => {
+      const resolution = resolveExternalToolUrl(tool, context)
+      // Placement is the ALREADY-SORTED position, not the declared `order`: the sort is stable,
+      // so tools sharing an order (the common case — nobody declares one) keep registration
+      // order instead of collapsing onto one nav slot.
+      const order = index
+      const contribution: NavContribution = {
+        id: tool.id,
+        // The title is deployment data, so it rides `label` (literal) rather than `labelKey`;
+        // `labelKey` still carries the section's own key so an accidental `t()` on it resolves.
+        labelKey: 'nav.externalTools',
+        label: tool.title,
+        description: tool.description,
+        icon: tool.icon,
+        surfaces: ['sidebar', 'command'],
+        testId: tool.testId ?? `nav-external-tool-${tool.id}`,
+        sidebar: { group: 'externalTools', order },
+        command: { group: 'externalTools', order },
+        run: () => {
+          // Re-resolve at CLICK time rather than reusing the projection's result: the context
+          // is reactive (a teammate can fill in `gameId` while this sidebar is open), and a
+          // captured stale resolution would keep reporting a fix that has already happened.
+          const now = resolveExternalToolUrl(tool, context)
+          if (now.ok) handlers.open(now.url, tool)
+          else handlers.onUnavailable(now, tool)
+        },
+      }
+      return { tool, resolution, contribution }
+    })
+}
+
+/**
+ * Drop the tools the caller may not see, on the same two independent axes as `navSlotFilter`
+ * applies to `nav`: the interface tier, then the item's own RBAC/availability predicate. With
+ * no gates service wired (tests, a bare install) everything passes, matching the dev-open
+ * "absent access allows all" parity the nav filter keeps.
+ */
+export function filterExternalTools(
+  tools: readonly ExternalToolContribution[],
+  gates: NavGates | undefined,
+): ExternalToolContribution[] {
+  if (!gates) return [...tools]
+  return tools.filter(
+    (t) => (t.advanced ? gates.advancedMode : true) && (t.gate ? t.gate(gates) : true),
+  )
+}

package/app/modular/nav-contributions.spec.ts

@@ -1,11 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import { hasI18nKey } from '../../test/i18nKeys'
 import {
+  COMMAND_GROUP_ORDER,
   groupCommands,
   groupSidebar,
   NAV_ACTIONS,
   NAV_CONTRIBUTIONS,
   navSlotFilter,
+  SIDEBAR_GROUP_ORDER,
   sortToolbar,
 } from './nav-contributions'
 import type { AppSlots, NavGates } from './nav-contributions'
@@ -60,6 +62,8 @@ const slots = (): AppSlots => ({
   taskTypeFormPanels: [],
   appOverlays: [],
   tutorialTours: [],
+  externalTools: [],
+  workspaceMetadataFields: [],
 })
 const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
 
@@ -212,6 +216,30 @@ describe('navSlotFilter', () => {
   })
 })
 
+describe('navSlotFilter external tools', () => {
+  const tools = [
+    { id: 'acme:a', title: 'A', icon: 'i-lucide-link', url: 'https://a.dev' },
+    {
+      id: 'acme:b',
+      title: 'B',
+      icon: 'i-lucide-link',
+      url: 'https://b.dev',
+      gate: (g: NavGates) => g.canManageIntegrations,
+    },
+  ]
+  const toolIds = (s: unknown) => (s as AppSlots).externalTools.map((t) => t.id)
+
+  it('gates registered tools in the SAME filter as the nav catalog', () => {
+    // They become nav items downstream (`useNavContributions` projects them), so gating them
+    // anywhere else would let a tool the caller can't use reach the palette while its sidebar
+    // twin was correctly hidden.
+    const withTools = (): AppSlots => ({ ...slots(), externalTools: [...tools] })
+    expect(toolIds(navSlotFilter(withTools(), { gates: ALL_GATES }))).toEqual(['acme:a', 'acme:b'])
+    expect(toolIds(navSlotFilter(withTools(), { gates: NO_GATES }))).toEqual(['acme:a'])
+    expect(toolIds(navSlotFilter(withTools(), {}))).toEqual(['acme:a', 'acme:b'])
+  })
+})
+
 describe('NAV_CONTRIBUTIONS catalog integrity', () => {
   it('has unique ids and every item targets at least one surface', () => {
     const seen = new Set<string>()
@@ -250,20 +278,10 @@ describe('NAV_CONTRIBUTIONS catalog integrity', () => {
     const check = (key: string | undefined) => {
       if (key && !hasKey(key)) missing.push(key)
     }
-    for (const group of ['create', 'repositories', 'integrations', 'workspace', 'account']) {
-      check(`layout.commandBar.groups.${group}`)
-    }
-    for (const group of [
-      'create',
-      'repositories',
-      'models',
-      'integrations',
-      'infrastructure',
-      'workspaceContext',
-      'configuration',
-    ]) {
-      check(`nav.${group}`)
-    }
+    // Derived from the canonical orders rather than re-listed, so a NEW section (the
+    // deployment-contributed `externalTools` one) can't be added without its header key.
+    for (const group of COMMAND_GROUP_ORDER) check(`layout.commandBar.groups.${group}`)
+    for (const group of SIDEBAR_GROUP_ORDER) check(`nav.${group}`)
     for (const item of NAV_CONTRIBUTIONS) {
       check(item.labelKey)
       if (item.command) {