@igstack/app-catalog-shared-core 1.0.0-alpha-20260913172344 → 1.0.0-alpha-20260914153414

package/dist/esm/__tests__/searchResources.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.d.ts

@@ -1 +1,2 @@
 export * from './nullToUndefined.js';
+export * from './searchResources.js';

package/dist/esm/index.js

@@ -1,6 +1,10 @@
 import { nullToUndefined, undefinedToNull } from "./nullToUndefined.js";
+import { searchResources, searchResourcesRanked, searchWithinApp } from "./searchResources.js";
 export {
   nullToUndefined,
+  searchResources,
+  searchResourcesRanked,
+  searchWithinApp,
   undefinedToNull
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/esm/searchResources.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Relevance ranking for catalog resources.
+ *
+ * Lives in shared-core so that every consumer — the catalog grid and the MCP
+ * server — ranks identically and cannot drift. It must NOT import `Resource`
+ * from backend-core: backend-core already depends on shared-core, so that would
+ * be a cycle. Instead the functions are generic over a structural
+ * `SearchableResource`, which `Resource` satisfies; each caller gets its own
+ * type back.
+ */
+/** The subset of a resource this engine reads. */
+export interface SearchableResource {
+    slug: string;
+    displayName: string;
+    abbreviation?: string;
+    nicknames?: string[];
+    aliases?: string[];
+    description?: string;
+    tags?: string[];
+    teams?: string[];
+    /** Undefined for top-level apps; the parent app's slug for sub-resources. */
+    parentSlug?: string;
+}
+export interface SearchMatch {
+    /** Field where the match occurred */
+    field: 'displayName' | 'abbreviation' | 'nicknames' | 'slug' | 'aliases' | 'tags' | 'teams' | 'description' | 'subResource';
+    /** Type of match */
+    type: 'exact' | 'prefix' | 'contains';
+}
+export interface SearchResult<T extends SearchableResource> {
+    app: T;
+    /**
+     * Which field matched and how. Absent only for the empty-query browse case,
+     * where nothing was matched against.
+     */
+    match?: SearchMatch;
+}
+/**
+ * Search and rank resources by relevance, keeping the match info.
+ *
+ * Only root resources (no `parentSlug`) are scored and returned. Child
+ * resources contribute to their parent's score — a query matching a child's
+ * displayName, alias or description surfaces the parent.
+ *
+ * Priority order:
+ * 0. Exact match in abbreviation
+ * 1. Exact match in displayName
+ * 2. Exact match in nickname
+ * 3. Prefix match in abbreviation
+ * 4. Prefix match in displayName
+ * 5. Prefix match in nickname
+ * 6. Exact match in tags
+ * 7. Prefix match in tags
+ * 8. Contains match in abbreviation
+ * 9. Contains match in displayName
+ * 10. Contains match in nickname
+ * 11. Contains match in tags
+ * 12. Teams
+ * 13. Sub-resource
+ * 14. Description
+ *
+ * @param resources - Array of all resources (roots + children)
+ * @param searchQuery - Search query string
+ * @returns Filtered and sorted root resources with their match info
+ */
+export declare function searchResourcesRanked<T extends SearchableResource>(resources: T[], searchQuery: string): SearchResult<T>[];
+/**
+ * Search and sort resources by relevance — the roots-only roll-up the catalog
+ * grid uses. Same ranking as {@link searchResourcesRanked}, without the match
+ * info.
+ */
+export declare function searchResources<T extends SearchableResource>(resources: T[], searchQuery: string): T[];
+/**
+ * Ranked search *within* one app's sub-resources — the `"<app>/<term>"` form.
+ *
+ * Matches a child's `displayName`, `slug`, `aliases` and `description`. Alias
+ * matching is load-bearing: in a deployment where every sub-resource carries a
+ * numeric alias, searching that bare number must find the sub-resource.
+ *
+ * @param resources - Array of all resources (roots + children)
+ * @param appSlug - Parent app slug whose children to search
+ * @param searchQuery - Search query string; empty returns every child
+ */
+export declare function searchWithinApp<T extends SearchableResource>(resources: T[], appSlug: string, searchQuery: string): SearchResult<T>[];

package/dist/esm/searchResources.js

@@ -0,0 +1,145 @@
+function allTermsMatcher(terms) {
+  return (text) => terms.every((term) => text.includes(term));
+}
+function searchResourcesRanked(resources, searchQuery) {
+  const normalizedQuery = searchQuery.trim().toLowerCase();
+  const rootResources = resources.filter((r) => !r.parentSlug);
+  if (normalizedQuery === "") {
+    return rootResources.map((app) => ({ app }));
+  }
+  const queryTerms = normalizedQuery.split(/\s+/).filter(Boolean);
+  const allTermsMatch = allTermsMatcher(queryTerms);
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const r of resources) {
+    if (r.parentSlug) {
+      const list = childrenByParent.get(r.parentSlug) ?? [];
+      list.push(r);
+      childrenByParent.set(r.parentSlug, list);
+    }
+  }
+  const scoredApps = rootResources.map((app) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const name = app.displayName.toLowerCase();
+    const abbreviation = ((_a = app.abbreviation) == null ? void 0 : _a.toLowerCase()) || "";
+    const nicknames = ((_b = app.nicknames) == null ? void 0 : _b.map((n) => n.toLowerCase())) || [];
+    const description = ((_c = app.description) == null ? void 0 : _c.toLowerCase()) || "";
+    const tags = ((_d = app.tags) == null ? void 0 : _d.join(" ").toLowerCase()) || "";
+    const teams = ((_e = app.teams) == null ? void 0 : _e.join(" ").toLowerCase()) || "";
+    const hit = (field, type, score) => ({ result: { app, match: { field, type } }, score });
+    if (abbreviation && abbreviation === normalizedQuery) {
+      return hit("abbreviation", "exact", 0);
+    }
+    if (name === normalizedQuery) {
+      return hit("displayName", "exact", 1);
+    }
+    if (nicknames.some((n) => n === normalizedQuery)) {
+      return hit("nicknames", "exact", 2);
+    }
+    if (abbreviation && abbreviation.startsWith(normalizedQuery)) {
+      return hit("abbreviation", "prefix", 3);
+    }
+    if (name.startsWith(normalizedQuery)) {
+      return hit("displayName", "prefix", 4);
+    }
+    if (nicknames.some((n) => n.startsWith(normalizedQuery))) {
+      return hit("nicknames", "prefix", 5);
+    }
+    if ((_f = app.tags) == null ? void 0 : _f.some((tag) => tag.toLowerCase() === normalizedQuery)) {
+      return hit("tags", "exact", 6);
+    }
+    if ((_g = app.tags) == null ? void 0 : _g.some((tag) => tag.toLowerCase().startsWith(normalizedQuery))) {
+      return hit("tags", "prefix", 7);
+    }
+    if (abbreviation && abbreviation.includes(normalizedQuery)) {
+      return hit("abbreviation", "contains", 8);
+    }
+    if (name.includes(normalizedQuery)) {
+      return hit("displayName", "contains", 9);
+    }
+    if (nicknames.some((n) => n.includes(normalizedQuery))) {
+      return hit("nicknames", "contains", 10);
+    }
+    if (tags.includes(normalizedQuery)) {
+      return hit("tags", "contains", 11);
+    }
+    if (allTermsMatch(teams)) {
+      return hit("teams", "contains", 12);
+    }
+    if (allTermsMatch(description)) {
+      return hit("description", "contains", 14);
+    }
+    const children = childrenByParent.get(app.slug);
+    if (children) {
+      const subMatch = children.some(
+        (r) => allTermsMatch(r.displayName.toLowerCase()) || (r.aliases ?? []).some((a) => allTermsMatch(a.toLowerCase())) || (r.description ? allTermsMatch(r.description.toLowerCase()) : false)
+      );
+      if (subMatch) {
+        return hit("subResource", "contains", 13);
+      }
+    }
+    return null;
+  }).filter(
+    (item) => item !== null
+  );
+  scoredApps.sort((a, b) => {
+    if (a.score !== b.score) {
+      return a.score - b.score;
+    }
+    return a.result.app.displayName.localeCompare(b.result.app.displayName);
+  });
+  return scoredApps.map((item) => item.result);
+}
+function searchResources(resources, searchQuery) {
+  return searchResourcesRanked(resources, searchQuery).map((r) => r.app);
+}
+function searchWithinApp(resources, appSlug, searchQuery) {
+  const children = resources.filter((r) => r.parentSlug === appSlug);
+  const normalizedQuery = searchQuery.trim().toLowerCase();
+  const byName = (a, b) => a.displayName.localeCompare(b.displayName);
+  if (normalizedQuery === "") {
+    return [...children].sort(byName).map((app) => ({ app }));
+  }
+  const queryTerms = normalizedQuery.split(/\s+/).filter(Boolean);
+  const allTermsMatch = allTermsMatcher(queryTerms);
+  const scored = children.map((app) => {
+    var _a, _b;
+    const name = app.displayName.toLowerCase();
+    const slug = app.slug.toLowerCase();
+    const aliases = ((_a = app.aliases) == null ? void 0 : _a.map((a) => a.toLowerCase())) ?? [];
+    const description = ((_b = app.description) == null ? void 0 : _b.toLowerCase()) ?? "";
+    const hit = (field, type, score) => ({ result: { app, match: { field, type } }, score });
+    if (name === normalizedQuery) return hit("displayName", "exact", 0);
+    if (slug === normalizedQuery) return hit("slug", "exact", 1);
+    if (aliases.some((a) => a === normalizedQuery)) {
+      return hit("aliases", "exact", 2);
+    }
+    if (name.startsWith(normalizedQuery)) {
+      return hit("displayName", "prefix", 3);
+    }
+    if (slug.startsWith(normalizedQuery)) return hit("slug", "prefix", 4);
+    if (aliases.some((a) => a.startsWith(normalizedQuery))) {
+      return hit("aliases", "prefix", 5);
+    }
+    if (allTermsMatch(name)) return hit("displayName", "contains", 6);
+    if (allTermsMatch(slug)) return hit("slug", "contains", 7);
+    if (aliases.some((a) => allTermsMatch(a))) {
+      return hit("aliases", "contains", 8);
+    }
+    if (description && allTermsMatch(description)) {
+      return hit("description", "contains", 9);
+    }
+    return null;
+  }).filter(
+    (item) => item !== null
+  );
+  scored.sort(
+    (a, b) => a.score !== b.score ? a.score - b.score : byName(a.result.app, b.result.app)
+  );
+  return scored.map((item) => item.result);
+}
+export {
+  searchResources,
+  searchResourcesRanked,
+  searchWithinApp
+};
+//# sourceMappingURL=searchResources.js.map

package/dist/esm/searchResources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchResources.js","sources":["../../src/searchResources.ts"],"sourcesContent":["/**\n * Relevance ranking for catalog resources.\n *\n * Lives in shared-core so that every consumer — the catalog grid and the MCP\n * server — ranks identically and cannot drift. It must NOT import `Resource`\n * from backend-core: backend-core already depends on shared-core, so that would\n * be a cycle. Instead the functions are generic over a structural\n * `SearchableResource`, which `Resource` satisfies; each caller gets its own\n * type back.\n */\n\n/** The subset of a resource this engine reads. */\nexport interface SearchableResource {\n  slug: string\n  displayName: string\n  abbreviation?: string\n  nicknames?: string[]\n  aliases?: string[]\n  description?: string\n  tags?: string[]\n  teams?: string[]\n  /** Undefined for top-level apps; the parent app's slug for sub-resources. */\n  parentSlug?: string\n}\n\nexport interface SearchMatch {\n  /** Field where the match occurred */\n  field:\n    | 'displayName'\n    | 'abbreviation'\n    | 'nicknames'\n    | 'slug'\n    | 'aliases'\n    | 'tags'\n    | 'teams'\n    | 'description'\n    | 'subResource'\n  /** Type of match */\n  type: 'exact' | 'prefix' | 'contains'\n}\n\nexport interface SearchResult<T extends SearchableResource> {\n  app: T\n  /**\n   * Which field matched and how. Absent only for the empty-query browse case,\n   * where nothing was matched against.\n   */\n  match?: SearchMatch\n}\n\n/** All terms appear in the text, order-independent (AND logic). */\nfunction allTermsMatcher(terms: string[]): (text: string) => boolean {\n  return (text: string) => terms.every((term) => text.includes(term))\n}\n\n/**\n * Search and rank resources by relevance, keeping the match info.\n *\n * Only root resources (no `parentSlug`) are scored and returned. Child\n * resources contribute to their parent's score — a query matching a child's\n * displayName, alias or description surfaces the parent.\n *\n * Priority order:\n * 0. Exact match in abbreviation\n * 1. Exact match in displayName\n * 2. Exact match in nickname\n * 3. Prefix match in abbreviation\n * 4. Prefix match in displayName\n * 5. Prefix match in nickname\n * 6. Exact match in tags\n * 7. Prefix match in tags\n * 8. Contains match in abbreviation\n * 9. Contains match in displayName\n * 10. Contains match in nickname\n * 11. Contains match in tags\n * 12. Teams\n * 13. Sub-resource\n * 14. Description\n *\n * @param resources - Array of all resources (roots + children)\n * @param searchQuery - Search query string\n * @returns Filtered and sorted root resources with their match info\n */\nexport function searchResourcesRanked<T extends SearchableResource>(\n  resources: T[],\n  searchQuery: string,\n): SearchResult<T>[] {\n  const normalizedQuery = searchQuery.trim().toLowerCase()\n\n  // Separate root resources from children\n  const rootResources = resources.filter((r) => !r.parentSlug)\n\n  if (normalizedQuery === '') {\n    return rootResources.map((app) => ({ app }))\n  }\n\n  // Split query into terms for multi-word matching (AND logic)\n  const queryTerms = normalizedQuery.split(/\\s+/).filter(Boolean)\n  const allTermsMatch = allTermsMatcher(queryTerms)\n\n  // Build children lookup: parentSlug -> T[]\n  const childrenByParent = new Map<string, T[]>()\n  for (const r of resources) {\n    if (r.parentSlug) {\n      const list = childrenByParent.get(r.parentSlug) ?? []\n      list.push(r)\n      childrenByParent.set(r.parentSlug, list)\n    }\n  }\n\n  // Filter and score root resources\n  const scoredApps = rootResources\n    .map((app): { result: SearchResult<T>; score: number } | null => {\n      const name = app.displayName.toLowerCase()\n      const abbreviation = app.abbreviation?.toLowerCase() || ''\n      const nicknames = app.nicknames?.map((n) => n.toLowerCase()) || []\n      const description = app.description?.toLowerCase() || ''\n      const tags = app.tags?.join(' ').toLowerCase() || ''\n      const teams = app.teams?.join(' ').toLowerCase() || ''\n\n      const hit = (\n        field: SearchMatch['field'],\n        type: SearchMatch['type'],\n        score: number,\n      ) => ({ result: { app, match: { field, type } }, score })\n\n      // Check exact matches first - prioritize abbreviation over displayName\n      if (abbreviation && abbreviation === normalizedQuery) {\n        return hit('abbreviation', 'exact', 0)\n      }\n      if (name === normalizedQuery) {\n        return hit('displayName', 'exact', 1)\n      }\n      if (nicknames.some((n) => n === normalizedQuery)) {\n        return hit('nicknames', 'exact', 2)\n      }\n\n      // Check prefix matches\n      if (abbreviation && abbreviation.startsWith(normalizedQuery)) {\n        return hit('abbreviation', 'prefix', 3)\n      }\n      if (name.startsWith(normalizedQuery)) {\n        return hit('displayName', 'prefix', 4)\n      }\n      if (nicknames.some((n) => n.startsWith(normalizedQuery))) {\n        return hit('nicknames', 'prefix', 5)\n      }\n\n      // Check exact match in tags (any tag exactly matches query)\n      if (app.tags?.some((tag) => tag.toLowerCase() === normalizedQuery)) {\n        return hit('tags', 'exact', 6)\n      }\n\n      // Check tags - prefix match (any tag starts with query)\n      if (\n        app.tags?.some((tag) => tag.toLowerCase().startsWith(normalizedQuery))\n      ) {\n        return hit('tags', 'prefix', 7)\n      }\n\n      // Check contains matches - prioritize abbreviation over displayName\n      if (abbreviation && abbreviation.includes(normalizedQuery)) {\n        return hit('abbreviation', 'contains', 8)\n      }\n      if (name.includes(normalizedQuery)) {\n        return hit('displayName', 'contains', 9)\n      }\n      if (nicknames.some((n) => n.includes(normalizedQuery))) {\n        return hit('nicknames', 'contains', 10)\n      }\n\n      // Check tags - contains match\n      if (tags.includes(normalizedQuery)) {\n        return hit('tags', 'contains', 11)\n      }\n\n      // Check teams (multi-word)\n      if (allTermsMatch(teams)) {\n        return hit('teams', 'contains', 12)\n      }\n\n      // Check description (multi-word)\n      if (allTermsMatch(description)) {\n        return hit('description', 'contains', 14)\n      }\n\n      // Check child resources (name, aliases, description) — supports\n      // multi-word queries. Alias matching is what makes a bare numeric\n      // identifier find its parent app in deployments where sub-resources\n      // carry numeric aliases.\n      const children = childrenByParent.get(app.slug)\n      if (children) {\n        const subMatch = children.some(\n          (r) =>\n            allTermsMatch(r.displayName.toLowerCase()) ||\n            (r.aliases ?? []).some((a) => allTermsMatch(a.toLowerCase())) ||\n            (r.description\n              ? allTermsMatch(r.description.toLowerCase())\n              : false),\n        )\n        if (subMatch) {\n          return hit('subResource', 'contains', 13)\n        }\n      }\n\n      // No match found\n      return null\n    })\n    .filter(\n      (item): item is { result: SearchResult<T>; score: number } =>\n        item !== null,\n    )\n\n  // Sort by score (ascending - lower score = higher priority)\n  scoredApps.sort((a, b) => {\n    if (a.score !== b.score) {\n      return a.score - b.score\n    }\n    // If same score, sort alphabetically by display name\n    return a.result.app.displayName.localeCompare(b.result.app.displayName)\n  })\n\n  return scoredApps.map((item) => item.result)\n}\n\n/**\n * Search and sort resources by relevance — the roots-only roll-up the catalog\n * grid uses. Same ranking as {@link searchResourcesRanked}, without the match\n * info.\n */\nexport function searchResources<T extends SearchableResource>(\n  resources: T[],\n  searchQuery: string,\n): T[] {\n  return searchResourcesRanked(resources, searchQuery).map((r) => r.app)\n}\n\n/**\n * Ranked search *within* one app's sub-resources — the `\"<app>/<term>\"` form.\n *\n * Matches a child's `displayName`, `slug`, `aliases` and `description`. Alias\n * matching is load-bearing: in a deployment where every sub-resource carries a\n * numeric alias, searching that bare number must find the sub-resource.\n *\n * @param resources - Array of all resources (roots + children)\n * @param appSlug - Parent app slug whose children to search\n * @param searchQuery - Search query string; empty returns every child\n */\nexport function searchWithinApp<T extends SearchableResource>(\n  resources: T[],\n  appSlug: string,\n  searchQuery: string,\n): SearchResult<T>[] {\n  const children = resources.filter((r) => r.parentSlug === appSlug)\n  const normalizedQuery = searchQuery.trim().toLowerCase()\n\n  const byName = (a: T, b: T) => a.displayName.localeCompare(b.displayName)\n\n  if (normalizedQuery === '') {\n    return [...children].sort(byName).map((app) => ({ app }))\n  }\n\n  const queryTerms = normalizedQuery.split(/\\s+/).filter(Boolean)\n  const allTermsMatch = allTermsMatcher(queryTerms)\n\n  const scored = children\n    .map((app): { result: SearchResult<T>; score: number } | null => {\n      const name = app.displayName.toLowerCase()\n      const slug = app.slug.toLowerCase()\n      const aliases = app.aliases?.map((a) => a.toLowerCase()) ?? []\n      const description = app.description?.toLowerCase() ?? ''\n\n      const hit = (\n        field: SearchMatch['field'],\n        type: SearchMatch['type'],\n        score: number,\n      ) => ({ result: { app, match: { field, type } }, score })\n\n      if (name === normalizedQuery) return hit('displayName', 'exact', 0)\n      if (slug === normalizedQuery) return hit('slug', 'exact', 1)\n      if (aliases.some((a) => a === normalizedQuery)) {\n        return hit('aliases', 'exact', 2)\n      }\n\n      if (name.startsWith(normalizedQuery)) {\n        return hit('displayName', 'prefix', 3)\n      }\n      if (slug.startsWith(normalizedQuery)) return hit('slug', 'prefix', 4)\n      if (aliases.some((a) => a.startsWith(normalizedQuery))) {\n        return hit('aliases', 'prefix', 5)\n      }\n\n      if (allTermsMatch(name)) return hit('displayName', 'contains', 6)\n      if (allTermsMatch(slug)) return hit('slug', 'contains', 7)\n      if (aliases.some((a) => allTermsMatch(a))) {\n        return hit('aliases', 'contains', 8)\n      }\n      if (description && allTermsMatch(description)) {\n        return hit('description', 'contains', 9)\n      }\n\n      return null\n    })\n    .filter(\n      (item): item is { result: SearchResult<T>; score: number } =>\n        item !== null,\n    )\n\n  scored.sort((a, b) =>\n    a.score !== b.score\n      ? a.score - b.score\n      : byName(a.result.app, b.result.app),\n  )\n\n  return scored.map((item) => item.result)\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-shared-core",
-  "version": "1.0.0-alpha-20260913172344",
+  "version": "1.0.0-alpha-20260914153414",
   "description": "Shared core utilities for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -42,7 +42,7 @@
   "engines": {
     "node": ">=16"
   },
-  "gitHead": "8203a6980bcd00fcb50dfc9a04408997a69f3130",
+  "gitHead": "c7c6a2375602656dffd01e81b151f3b9adcdc97f",
   "scripts": {
     "build": "vite build",
     "clean": "premove ./dist ./coverage ./dist-ts",

package/src/__tests__/searchResources.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, it } from 'vitest'
+import type { SearchableResource } from '../searchResources'
+import {
+  searchResources,
+  searchResourcesRanked,
+  searchWithinApp,
+} from '../searchResources'
+
+function makeApp(
+  overrides: Partial<SearchableResource> & { slug: string },
+): SearchableResource {
+  return {
+    displayName: overrides.slug,
+    ...overrides,
+  }
+}
+
+function makeChildResource(
+  overrides: Partial<SearchableResource> & {
+    slug: string
+    parentSlug: string
+  },
+): SearchableResource {
+  return {
+    displayName: overrides.slug,
+    aliases: [],
+    ...overrides,
+  }
+}
+
+describe('searchResources', () => {
+  const apps: SearchableResource[] = [
+    makeApp({
+      slug: 'taskflow',
+      displayName: 'TaskFlow',
+      description: 'Issue tracker',
+    }),
+    makeApp({
+      slug: 'aws-console',
+      displayName: 'AWS Console',
+      description: 'Cloud management',
+    }),
+    makeApp({
+      slug: 'teamchat',
+      displayName: 'TeamChat',
+      description: 'Messaging',
+    }),
+  ]
+
+  it('returns all root apps when query is empty', () => {
+    expect(searchResources(apps, '')).toHaveLength(3)
+  })
+
+  it('finds app by displayName', () => {
+    const results = searchResources(apps, 'taskflow')
+    expect(results).toHaveLength(1)
+    expect(results[0]!.slug).toBe('taskflow')
+  })
+
+  it('finds app by nickname and by abbreviation', () => {
+    const withAliases = [
+      ...apps,
+      makeApp({
+        slug: 'lab-system',
+        displayName: 'Laboratory System',
+        abbreviation: 'LS',
+        nicknames: ['labsys'],
+      }),
+    ]
+    expect(searchResources(withAliases, 'labsys')[0]!.slug).toBe('lab-system')
+    expect(searchResources(withAliases, 'ls')[0]!.slug).toBe('lab-system')
+  })
+
+  describe('child resource search', () => {
+    const childResources: SearchableResource[] = [
+      makeChildResource({
+        slug: 'aws-acme-pipelines-dev',
+        displayName: 'acme-pipelines-data-analytics-dev',
+        parentSlug: 'aws-console',
+        aliases: ['000000000001'],
+      }),
+      makeChildResource({
+        slug: 'aws-acme-infosec-dev',
+        displayName: 'acme-infosec-dev',
+        parentSlug: 'aws-console',
+        aliases: [],
+      }),
+    ]
+
+    const allResources = [...apps, ...childResources]
+
+    it('finds app by child resource displayName', () => {
+      const results = searchResources(allResources, 'pipelines data-analytics')
+      expect(results).toHaveLength(1)
+      expect(results[0]!.slug).toBe('aws-console')
+    })
+
+    it('finds app by child resource alias (numeric account identifier)', () => {
+      const results = searchResources(allResources, '000000000001')
+      expect(results).toHaveLength(1)
+      expect(results[0]!.slug).toBe('aws-console')
+    })
+
+    it('does not match child resources when none provided', () => {
+      const results = searchResources(apps, '000000000001')
+      expect(results).toHaveLength(0)
+    })
+
+    it('direct app match ranks higher than child resource match', () => {
+      const results = searchResources(allResources, 'aws')
+      // 'aws-console' matches by displayName, should appear
+      expect(results.length).toBeGreaterThanOrEqual(1)
+      expect(results[0]!.slug).toBe('aws-console')
+    })
+
+    it('never returns children from the roots-only roll-up', () => {
+      const results = searchResources(allResources, '')
+      expect(results.map((r) => r.slug)).toEqual([
+        'taskflow',
+        'aws-console',
+        'teamchat',
+      ])
+    })
+  })
+})
+
+describe('searchResourcesRanked', () => {
+  const apps: SearchableResource[] = [
+    makeApp({ slug: 'taskflow', displayName: 'TaskFlow' }),
+    makeApp({
+      slug: 'teamchat',
+      displayName: 'TeamChat',
+      description: 'taskflow rival',
+    }),
+  ]
+
+  it('reports which field matched and how', () => {
+    const results = searchResourcesRanked(apps, 'taskflow')
+    expect(
+      results.map((r) => [r.app.slug, r.match?.field, r.match?.type]),
+    ).toEqual([
+      ['taskflow', 'displayName', 'exact'],
+      ['teamchat', 'description', 'contains'],
+    ])
+  })
+
+  it('returns the same order as searchResources', () => {
+    expect(searchResourcesRanked(apps, 'taskflow').map((r) => r.app)).toEqual(
+      searchResources(apps, 'taskflow'),
+    )
+  })
+})
+
+describe('searchWithinApp', () => {
+  const resources: SearchableResource[] = [
+    makeApp({ slug: 'aws-console', displayName: 'AWS Console' }),
+    makeApp({ slug: 'taskflow', displayName: 'TaskFlow' }),
+    makeChildResource({
+      slug: 'aws-acme-biomarkers-prod',
+      displayName: 'acme-biomarkers-prod',
+      parentSlug: 'aws-console',
+      aliases: ['000000000001'],
+      description: 'Cloud account: acme-biomarkers-prod',
+    }),
+    makeChildResource({
+      slug: 'aws-acme-biomarkers-dev',
+      displayName: 'acme-biomarkers-dev',
+      parentSlug: 'aws-console',
+      aliases: ['000000000002'],
+    }),
+    makeChildResource({
+      slug: 'aws-acme-infosec-dev',
+      displayName: 'acme-infosec-dev',
+      parentSlug: 'aws-console',
+      aliases: ['000000000003'],
+    }),
+    makeChildResource({
+      slug: 'tf-child',
+      displayName: 'biomarkers-board',
+      parentSlug: 'taskflow',
+      aliases: [],
+    }),
+  ]
+
+  it('searches only the named app’s children', () => {
+    const results = searchWithinApp(resources, 'aws-console', 'biomarkers')
+    expect(results.map((r) => r.app.slug)).toEqual([
+      'aws-acme-biomarkers-dev',
+      'aws-acme-biomarkers-prod',
+    ])
+  })
+
+  it('matches a bare numeric alias — the account-number lookup', () => {
+    const results = searchWithinApp(resources, 'aws-console', '000000000001')
+    expect(results).toHaveLength(1)
+    expect(results[0]!.app.slug).toBe('aws-acme-biomarkers-prod')
+    expect(results[0]!.match).toEqual({ field: 'aliases', type: 'exact' })
+  })
+
+  it('matches on slug and on description', () => {
+    expect(
+      searchWithinApp(resources, 'aws-console', 'aws-acme-infosec-dev'),
+    ).toHaveLength(1)
+    expect(
+      searchWithinApp(resources, 'aws-console', 'cloud account'),
+    ).toHaveLength(1)
+  })
+
+  it('returns every child for an empty query, alphabetically', () => {
+    expect(
+      searchWithinApp(resources, 'aws-console', '').map((r) => r.app.slug),
+    ).toEqual([
+      'aws-acme-biomarkers-dev',
+      'aws-acme-biomarkers-prod',
+      'aws-acme-infosec-dev',
+    ])
+  })
+
+  it('returns nothing for an app without children or a miss', () => {
+    expect(searchWithinApp(resources, 'nope', 'biomarkers')).toEqual([])
+    expect(searchWithinApp(resources, 'aws-console', 'zzzz')).toEqual([])
+  })
+})

package/src/index.ts

@@ -1 +1,2 @@
 export * from './nullToUndefined'
+export * from './searchResources'

package/src/searchResources.ts

@@ -0,0 +1,316 @@
+/**
+ * Relevance ranking for catalog resources.
+ *
+ * Lives in shared-core so that every consumer — the catalog grid and the MCP
+ * server — ranks identically and cannot drift. It must NOT import `Resource`
+ * from backend-core: backend-core already depends on shared-core, so that would
+ * be a cycle. Instead the functions are generic over a structural
+ * `SearchableResource`, which `Resource` satisfies; each caller gets its own
+ * type back.
+ */
+
+/** The subset of a resource this engine reads. */
+export interface SearchableResource {
+  slug: string
+  displayName: string
+  abbreviation?: string
+  nicknames?: string[]
+  aliases?: string[]
+  description?: string
+  tags?: string[]
+  teams?: string[]
+  /** Undefined for top-level apps; the parent app's slug for sub-resources. */
+  parentSlug?: string
+}
+
+export interface SearchMatch {
+  /** Field where the match occurred */
+  field:
+    | 'displayName'
+    | 'abbreviation'
+    | 'nicknames'
+    | 'slug'
+    | 'aliases'
+    | 'tags'
+    | 'teams'
+    | 'description'
+    | 'subResource'
+  /** Type of match */
+  type: 'exact' | 'prefix' | 'contains'
+}
+
+export interface SearchResult<T extends SearchableResource> {
+  app: T
+  /**
+   * Which field matched and how. Absent only for the empty-query browse case,
+   * where nothing was matched against.
+   */
+  match?: SearchMatch
+}
+
+/** All terms appear in the text, order-independent (AND logic). */
+function allTermsMatcher(terms: string[]): (text: string) => boolean {
+  return (text: string) => terms.every((term) => text.includes(term))
+}
+
+/**
+ * Search and rank resources by relevance, keeping the match info.
+ *
+ * Only root resources (no `parentSlug`) are scored and returned. Child
+ * resources contribute to their parent's score — a query matching a child's
+ * displayName, alias or description surfaces the parent.
+ *
+ * Priority order:
+ * 0. Exact match in abbreviation
+ * 1. Exact match in displayName
+ * 2. Exact match in nickname
+ * 3. Prefix match in abbreviation
+ * 4. Prefix match in displayName
+ * 5. Prefix match in nickname
+ * 6. Exact match in tags
+ * 7. Prefix match in tags
+ * 8. Contains match in abbreviation
+ * 9. Contains match in displayName
+ * 10. Contains match in nickname
+ * 11. Contains match in tags
+ * 12. Teams
+ * 13. Sub-resource
+ * 14. Description
+ *
+ * @param resources - Array of all resources (roots + children)
+ * @param searchQuery - Search query string
+ * @returns Filtered and sorted root resources with their match info
+ */
+export function searchResourcesRanked<T extends SearchableResource>(
+  resources: T[],
+  searchQuery: string,
+): SearchResult<T>[] {
+  const normalizedQuery = searchQuery.trim().toLowerCase()
+
+  // Separate root resources from children
+  const rootResources = resources.filter((r) => !r.parentSlug)
+
+  if (normalizedQuery === '') {
+    return rootResources.map((app) => ({ app }))
+  }
+
+  // Split query into terms for multi-word matching (AND logic)
+  const queryTerms = normalizedQuery.split(/\s+/).filter(Boolean)
+  const allTermsMatch = allTermsMatcher(queryTerms)
+
+  // Build children lookup: parentSlug -> T[]
+  const childrenByParent = new Map<string, T[]>()
+  for (const r of resources) {
+    if (r.parentSlug) {
+      const list = childrenByParent.get(r.parentSlug) ?? []
+      list.push(r)
+      childrenByParent.set(r.parentSlug, list)
+    }
+  }
+
+  // Filter and score root resources
+  const scoredApps = rootResources
+    .map((app): { result: SearchResult<T>; score: number } | null => {
+      const name = app.displayName.toLowerCase()
+      const abbreviation = app.abbreviation?.toLowerCase() || ''
+      const nicknames = app.nicknames?.map((n) => n.toLowerCase()) || []
+      const description = app.description?.toLowerCase() || ''
+      const tags = app.tags?.join(' ').toLowerCase() || ''
+      const teams = app.teams?.join(' ').toLowerCase() || ''
+
+      const hit = (
+        field: SearchMatch['field'],
+        type: SearchMatch['type'],
+        score: number,
+      ) => ({ result: { app, match: { field, type } }, score })
+
+      // Check exact matches first - prioritize abbreviation over displayName
+      if (abbreviation && abbreviation === normalizedQuery) {
+        return hit('abbreviation', 'exact', 0)
+      }
+      if (name === normalizedQuery) {
+        return hit('displayName', 'exact', 1)
+      }
+      if (nicknames.some((n) => n === normalizedQuery)) {
+        return hit('nicknames', 'exact', 2)
+      }
+
+      // Check prefix matches
+      if (abbreviation && abbreviation.startsWith(normalizedQuery)) {
+        return hit('abbreviation', 'prefix', 3)
+      }
+      if (name.startsWith(normalizedQuery)) {
+        return hit('displayName', 'prefix', 4)
+      }
+      if (nicknames.some((n) => n.startsWith(normalizedQuery))) {
+        return hit('nicknames', 'prefix', 5)
+      }
+
+      // Check exact match in tags (any tag exactly matches query)
+      if (app.tags?.some((tag) => tag.toLowerCase() === normalizedQuery)) {
+        return hit('tags', 'exact', 6)
+      }
+
+      // Check tags - prefix match (any tag starts with query)
+      if (
+        app.tags?.some((tag) => tag.toLowerCase().startsWith(normalizedQuery))
+      ) {
+        return hit('tags', 'prefix', 7)
+      }
+
+      // Check contains matches - prioritize abbreviation over displayName
+      if (abbreviation && abbreviation.includes(normalizedQuery)) {
+        return hit('abbreviation', 'contains', 8)
+      }
+      if (name.includes(normalizedQuery)) {
+        return hit('displayName', 'contains', 9)
+      }
+      if (nicknames.some((n) => n.includes(normalizedQuery))) {
+        return hit('nicknames', 'contains', 10)
+      }
+
+      // Check tags - contains match
+      if (tags.includes(normalizedQuery)) {
+        return hit('tags', 'contains', 11)
+      }
+
+      // Check teams (multi-word)
+      if (allTermsMatch(teams)) {
+        return hit('teams', 'contains', 12)
+      }
+
+      // Check description (multi-word)
+      if (allTermsMatch(description)) {
+        return hit('description', 'contains', 14)
+      }
+
+      // Check child resources (name, aliases, description) — supports
+      // multi-word queries. Alias matching is what makes a bare numeric
+      // identifier find its parent app in deployments where sub-resources
+      // carry numeric aliases.
+      const children = childrenByParent.get(app.slug)
+      if (children) {
+        const subMatch = children.some(
+          (r) =>
+            allTermsMatch(r.displayName.toLowerCase()) ||
+            (r.aliases ?? []).some((a) => allTermsMatch(a.toLowerCase())) ||
+            (r.description
+              ? allTermsMatch(r.description.toLowerCase())
+              : false),
+        )
+        if (subMatch) {
+          return hit('subResource', 'contains', 13)
+        }
+      }
+
+      // No match found
+      return null
+    })
+    .filter(
+      (item): item is { result: SearchResult<T>; score: number } =>
+        item !== null,
+    )
+
+  // Sort by score (ascending - lower score = higher priority)
+  scoredApps.sort((a, b) => {
+    if (a.score !== b.score) {
+      return a.score - b.score
+    }
+    // If same score, sort alphabetically by display name
+    return a.result.app.displayName.localeCompare(b.result.app.displayName)
+  })
+
+  return scoredApps.map((item) => item.result)
+}
+
+/**
+ * Search and sort resources by relevance — the roots-only roll-up the catalog
+ * grid uses. Same ranking as {@link searchResourcesRanked}, without the match
+ * info.
+ */
+export function searchResources<T extends SearchableResource>(
+  resources: T[],
+  searchQuery: string,
+): T[] {
+  return searchResourcesRanked(resources, searchQuery).map((r) => r.app)
+}
+
+/**
+ * Ranked search *within* one app's sub-resources — the `"<app>/<term>"` form.
+ *
+ * Matches a child's `displayName`, `slug`, `aliases` and `description`. Alias
+ * matching is load-bearing: in a deployment where every sub-resource carries a
+ * numeric alias, searching that bare number must find the sub-resource.
+ *
+ * @param resources - Array of all resources (roots + children)
+ * @param appSlug - Parent app slug whose children to search
+ * @param searchQuery - Search query string; empty returns every child
+ */
+export function searchWithinApp<T extends SearchableResource>(
+  resources: T[],
+  appSlug: string,
+  searchQuery: string,
+): SearchResult<T>[] {
+  const children = resources.filter((r) => r.parentSlug === appSlug)
+  const normalizedQuery = searchQuery.trim().toLowerCase()
+
+  const byName = (a: T, b: T) => a.displayName.localeCompare(b.displayName)
+
+  if (normalizedQuery === '') {
+    return [...children].sort(byName).map((app) => ({ app }))
+  }
+
+  const queryTerms = normalizedQuery.split(/\s+/).filter(Boolean)
+  const allTermsMatch = allTermsMatcher(queryTerms)
+
+  const scored = children
+    .map((app): { result: SearchResult<T>; score: number } | null => {
+      const name = app.displayName.toLowerCase()
+      const slug = app.slug.toLowerCase()
+      const aliases = app.aliases?.map((a) => a.toLowerCase()) ?? []
+      const description = app.description?.toLowerCase() ?? ''
+
+      const hit = (
+        field: SearchMatch['field'],
+        type: SearchMatch['type'],
+        score: number,
+      ) => ({ result: { app, match: { field, type } }, score })
+
+      if (name === normalizedQuery) return hit('displayName', 'exact', 0)
+      if (slug === normalizedQuery) return hit('slug', 'exact', 1)
+      if (aliases.some((a) => a === normalizedQuery)) {
+        return hit('aliases', 'exact', 2)
+      }
+
+      if (name.startsWith(normalizedQuery)) {
+        return hit('displayName', 'prefix', 3)
+      }
+      if (slug.startsWith(normalizedQuery)) return hit('slug', 'prefix', 4)
+      if (aliases.some((a) => a.startsWith(normalizedQuery))) {
+        return hit('aliases', 'prefix', 5)
+      }
+
+      if (allTermsMatch(name)) return hit('displayName', 'contains', 6)
+      if (allTermsMatch(slug)) return hit('slug', 'contains', 7)
+      if (aliases.some((a) => allTermsMatch(a))) {
+        return hit('aliases', 'contains', 8)
+      }
+      if (description && allTermsMatch(description)) {
+        return hit('description', 'contains', 9)
+      }
+
+      return null
+    })
+    .filter(
+      (item): item is { result: SearchResult<T>; score: number } =>
+        item !== null,
+    )
+
+  scored.sort((a, b) =>
+    a.score !== b.score
+      ? a.score - b.score
+      : byName(a.result.app, b.result.app),
+  )
+
+  return scored.map((item) => item.result)
+}