@igstack/app-catalog-shared-core 2.0.1-alpha-20260228221600 → 2.0.1-alpha-20260915181451

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

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

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

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

package/dist/esm/appCatalogTypes.d.ts

@@ -20,19 +20,19 @@ export type ApprovalType = 'none' | 'service' | 'person' | 'other' | 'unknown';
 /**
  * Approval type options for UI display
  */
-export declare const APPROVAL_TYPES: ReadonlyArray<{
+export declare const APPROVAL_TYPES: readonly {
     value: ApprovalType;
     label: string;
-}>;
+}[];
 /**
  * Common fields for all approval method types
  */
 export interface BaseApprovalMethod {
     comment?: string;
-    roles?: Array<AppRole>;
+    roles?: AppRole[];
     approvalPolicy?: string;
     postApprovalInstructions?: string;
-    seeMoreUrls?: Array<string>;
+    seeMoreUrls?: string[];
 }
 /**
  * Service-based approval (bot or ticketing system)
@@ -106,22 +106,22 @@ export interface AppForCatalog {
     displayName: string;
     description?: string;
     approvalMethod?: ApprovalMethod;
-    teams?: Array<string>;
+    teams?: string[];
     notes?: string;
-    tags?: Array<string>;
+    tags?: string[];
     appUrl?: string;
-    links?: Array<{
+    links?: {
         url: string;
         title?: string;
-    }>;
+    }[];
     iconName?: string;
-    screenshotIds?: Array<string>;
+    screenshotIds?: string[];
 }
 export interface AppCategory {
     id: string;
     name: string;
 }
 export interface AppCatalogData {
-    apps: Array<AppForCatalog>;
-    categories: Array<AppCategory>;
+    apps: AppForCatalog[];
+    categories: AppCategory[];
 }

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/nullToUndefined.d.ts

@@ -1,8 +1,8 @@
 import { Primitive } from 'type-fest';
-export type NullToUndefined<T> = T extends null ? undefined : T extends Primitive | Function | Date | RegExp ? T : T extends Array<infer U> ? Array<NullToUndefined<U>> : T extends Map<infer K, infer V> ? Map<K, NullToUndefined<V>> : T extends Set<infer U> ? Set<NullToUndefined<U>> : T extends object ? {
+export type NullToUndefined<T> = T extends null ? undefined : T extends Primitive | Function | Date | RegExp ? T : T extends (infer U)[] ? NullToUndefined<U>[] : T extends Map<infer K, infer V> ? Map<K, NullToUndefined<V>> : T extends Set<infer U> ? Set<NullToUndefined<U>> : T extends object ? {
     [K in keyof T]: NullToUndefined<T[K]>;
 } : unknown;
-export type UndefinedToNull<T> = T extends undefined ? null : T extends Primitive | Function | Date | RegExp ? T : T extends Array<infer U> ? Array<UndefinedToNull<U>> : T extends Map<infer K, infer V> ? Map<K, UndefinedToNull<V>> : T extends Set<infer U> ? Set<NullToUndefined<U>> : T extends object ? {
+export type UndefinedToNull<T> = T extends undefined ? null : T extends Primitive | Function | Date | RegExp ? T : T extends (infer U)[] ? UndefinedToNull<U>[] : T extends Map<infer K, infer V> ? Map<K, UndefinedToNull<V>> : T extends Set<infer U> ? Set<NullToUndefined<U>> : T extends object ? {
     [K in keyof T]: UndefinedToNull<T[K]>;
 } : unknown;
 /**

package/dist/esm/nullToUndefined.js.map

@@ -1 +1 @@
-{"version":3,"file":"nullToUndefined.js","sources":["../../src/nullToUndefined.ts"],"sourcesContent":["import type { Primitive } from 'type-fest'\n\n/*\n  Taken from https://gist.github.com/tkrotoff/a6baf96eb6b61b445a9142e5555511a0\n * [Generic way to convert all instances of null to undefined in TypeScript](https://stackoverflow.com/q/50374869)\n *\n * This only works with JS objects hence the file name *Object*Values\n *\n * [\"I intend to stop using `null` in my JS code in favor of `undefined`\"](https://github.com/sindresorhus/meta/discussions/7)\n * [Proposal: NullToUndefined and UndefinedToNull](https://github.com/sindresorhus/type-fest/issues/603)\n *\n * Types implementation inspired by:\n * - https://github.com/sindresorhus/type-fest/blob/v2.12.2/source/delimiter-cased-properties-deep.d.ts\n * - https://github.com/sindresorhus/type-fest/blob/v2.12.2/source/readonly-deep.d.ts\n *\n * https://gist.github.com/tkrotoff/a6baf96eb6b61b445a9142e5555511a0\n */\nexport type NullToUndefined<T> = T extends null\n  ? undefined\n  : T extends Primitive | Function | Date | RegExp\n    ? T\n    : T extends Array<infer U>\n      ? Array<NullToUndefined<U>>\n      : T extends Map<infer K, infer V>\n        ? Map<K, NullToUndefined<V>>\n        : T extends Set<infer U>\n          ? Set<NullToUndefined<U>>\n          : T extends object\n            ? { [K in keyof T]: NullToUndefined<T[K]> }\n            : unknown\n\nexport type UndefinedToNull<T> = T extends undefined\n  ? null\n  : T extends Primitive | Function | Date | RegExp\n    ? T\n    : T extends Array<infer U>\n      ? Array<UndefinedToNull<U>>\n      : T extends Map<infer K, infer V>\n        ? Map<K, UndefinedToNull<V>>\n        : T extends Set<infer U>\n          ? Set<NullToUndefined<U>>\n          : T extends object\n            ? { [K in keyof T]: UndefinedToNull<T[K]> }\n            : unknown\n\nfunction _nullToUndefined<T>(obj: T): NullToUndefined<T> {\n  if (obj === null) {\n    return undefined as any\n  }\n\n  if (typeof obj === 'object') {\n    if (obj instanceof Map) {\n      obj.forEach((value, key) => obj.set(key, _nullToUndefined(value)))\n    } else {\n      for (const key in obj) {\n        obj[key] = _nullToUndefined(obj[key]) as any\n      }\n    }\n  }\n\n  return obj as any\n}\n\n/**\n * Recursively converts all null values to undefined.\n *\n * @param obj object to convert\n * @returns a copy of the object with all its null values converted to undefined\n */\nexport function nullToUndefined<\n  T,\n  // Can cause: \"Type instantiation is excessively deep and possibly infinite.\"\n  // extends Jsonifiable\n>(obj: T) {\n  return _nullToUndefined(structuredClone(obj))\n}\n\nfunction _undefinedToNull<T>(obj: T): UndefinedToNull<T> {\n  if (obj === undefined) {\n    return null as any\n  }\n\n  if (typeof obj === 'object') {\n    if (obj instanceof Map) {\n      obj.forEach((value, key) => obj.set(key, _undefinedToNull(value)))\n    } else {\n      for (const key in obj) {\n        obj[key] = _undefinedToNull(obj[key]) as any\n      }\n    }\n  }\n\n  return obj as any\n}\n\n/**\n * Recursively converts all undefined values to null.\n *\n * @param obj object to convert\n * @returns a copy of the object with all its undefined values converted to null\n */\nexport function undefinedToNull<\n  T,\n  // Can cause: \"Type instantiation is excessively deep and possibly infinite.\"\n  // extends Jsonifiable\n>(obj: T) {\n  return _undefinedToNull(structuredClone(obj))\n}\n"],"names":[],"mappings":"AA6CA,SAAS,iBAAoB,KAA4B;AACvD,MAAI,QAAQ,MAAM;AAChB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,QAAQ,UAAU;AAC3B,QAAI,eAAe,KAAK;AACtB,UAAI,QAAQ,CAAC,OAAO,QAAQ,IAAI,IAAI,KAAK,iBAAiB,KAAK,CAAC,CAAC;AAAA,IACnE,OAAO;AACL,iBAAW,OAAO,KAAK;AACrB,YAAI,GAAG,IAAI,iBAAiB,IAAI,GAAG,CAAC;AAAA,MACtC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,gBAId,KAAQ;AACR,SAAO,iBAAiB,gBAAgB,GAAG,CAAC;AAC9C;AAEA,SAAS,iBAAoB,KAA4B;AACvD,MAAI,QAAQ,QAAW;AACrB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,QAAQ,UAAU;AAC3B,QAAI,eAAe,KAAK;AACtB,UAAI,QAAQ,CAAC,OAAO,QAAQ,IAAI,IAAI,KAAK,iBAAiB,KAAK,CAAC,CAAC;AAAA,IACnE,OAAO;AACL,iBAAW,OAAO,KAAK;AACrB,YAAI,GAAG,IAAI,iBAAiB,IAAI,GAAG,CAAC;AAAA,MACtC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,gBAId,KAAQ;AACR,SAAO,iBAAiB,gBAAgB,GAAG,CAAC;AAC9C;"}
+{"version":3,"file":"nullToUndefined.js","sources":["../../src/nullToUndefined.ts"],"sourcesContent":["import type { Primitive } from 'type-fest'\n\n/*\n  Taken from https://gist.github.com/tkrotoff/a6baf96eb6b61b445a9142e5555511a0\n * [Generic way to convert all instances of null to undefined in TypeScript](https://stackoverflow.com/q/50374869)\n *\n * This only works with JS objects hence the file name *Object*Values\n *\n * [\"I intend to stop using `null` in my JS code in favor of `undefined`\"](https://github.com/sindresorhus/meta/discussions/7)\n * [Proposal: NullToUndefined and UndefinedToNull](https://github.com/sindresorhus/type-fest/issues/603)\n *\n * Types implementation inspired by:\n * - https://github.com/sindresorhus/type-fest/blob/v2.12.2/source/delimiter-cased-properties-deep.d.ts\n * - https://github.com/sindresorhus/type-fest/blob/v2.12.2/source/readonly-deep.d.ts\n *\n * https://gist.github.com/tkrotoff/a6baf96eb6b61b445a9142e5555511a0\n */\nexport type NullToUndefined<T> = T extends null\n  ? undefined\n  : T extends Primitive | Function | Date | RegExp\n    ? T\n    : T extends (infer U)[]\n      ? NullToUndefined<U>[]\n      : T extends Map<infer K, infer V>\n        ? Map<K, NullToUndefined<V>>\n        : T extends Set<infer U>\n          ? Set<NullToUndefined<U>>\n          : T extends object\n            ? { [K in keyof T]: NullToUndefined<T[K]> }\n            : unknown\n\nexport type UndefinedToNull<T> = T extends undefined\n  ? null\n  : T extends Primitive | Function | Date | RegExp\n    ? T\n    : T extends (infer U)[]\n      ? UndefinedToNull<U>[]\n      : T extends Map<infer K, infer V>\n        ? Map<K, UndefinedToNull<V>>\n        : T extends Set<infer U>\n          ? Set<NullToUndefined<U>>\n          : T extends object\n            ? { [K in keyof T]: UndefinedToNull<T[K]> }\n            : unknown\n\nfunction _nullToUndefined<T>(obj: T): NullToUndefined<T> {\n  if (obj === null) {\n    return undefined as any\n  }\n\n  if (typeof obj === 'object') {\n    if (obj instanceof Map) {\n      obj.forEach((value, key) => obj.set(key, _nullToUndefined(value)))\n    } else {\n      for (const key in obj) {\n        obj[key] = _nullToUndefined(obj[key]) as any\n      }\n    }\n  }\n\n  return obj as any\n}\n\n/**\n * Recursively converts all null values to undefined.\n *\n * @param obj object to convert\n * @returns a copy of the object with all its null values converted to undefined\n */\nexport function nullToUndefined<\n  T,\n  // Can cause: \"Type instantiation is excessively deep and possibly infinite.\"\n  // extends Jsonifiable\n>(obj: T) {\n  return _nullToUndefined(structuredClone(obj))\n}\n\nfunction _undefinedToNull<T>(obj: T): UndefinedToNull<T> {\n  if (obj === undefined) {\n    return null as any\n  }\n\n  if (typeof obj === 'object') {\n    if (obj instanceof Map) {\n      obj.forEach((value, key) => obj.set(key, _undefinedToNull(value)))\n    } else {\n      for (const key in obj) {\n        obj[key] = _undefinedToNull(obj[key]) as any\n      }\n    }\n  }\n\n  return obj as any\n}\n\n/**\n * Recursively converts all undefined values to null.\n *\n * @param obj object to convert\n * @returns a copy of the object with all its undefined values converted to null\n */\nexport function undefinedToNull<\n  T,\n  // Can cause: \"Type instantiation is excessively deep and possibly infinite.\"\n  // extends Jsonifiable\n>(obj: T) {\n  return _undefinedToNull(structuredClone(obj))\n}\n"],"names":[],"mappings":"AA6CA,SAAS,iBAAoB,KAA4B;AACvD,MAAI,QAAQ,MAAM;AAChB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,QAAQ,UAAU;AAC3B,QAAI,eAAe,KAAK;AACtB,UAAI,QAAQ,CAAC,OAAO,QAAQ,IAAI,IAAI,KAAK,iBAAiB,KAAK,CAAC,CAAC;AAAA,IACnE,OAAO;AACL,iBAAW,OAAO,KAAK;AACrB,YAAI,GAAG,IAAI,iBAAiB,IAAI,GAAG,CAAC;AAAA,MACtC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,gBAId,KAAQ;AACR,SAAO,iBAAiB,gBAAgB,GAAG,CAAC;AAC9C;AAEA,SAAS,iBAAoB,KAA4B;AACvD,MAAI,QAAQ,QAAW;AACrB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,QAAQ,UAAU;AAC3B,QAAI,eAAe,KAAK;AACtB,UAAI,QAAQ,CAAC,OAAO,QAAQ,IAAI,IAAI,KAAK,iBAAiB,KAAK,CAAC,CAAC;AAAA,IACnE,OAAO;AACL,iBAAW,OAAO,KAAK;AACrB,YAAI,GAAG,IAAI,iBAAiB,IAAI,GAAG,CAAC;AAAA,MACtC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,gBAId,KAAQ;AACR,SAAO,iBAAiB,gBAAgB,GAAG,CAAC;AAC9C;"}

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": "2.0.1-alpha-20260228221600",
+  "version": "2.0.1-alpha-20260915181451",
   "description": "Shared core utilities for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -37,17 +37,20 @@
     "@types/node": "^24.3.0",
     "esbuild": "^0.25.5",
     "tsx": "^4.19.4",
-    "typescript": "5.9.2"
+    "typescript": "5.9.3"
   },
   "engines": {
     "node": ">=16"
   },
+  "gitHead": "7723c1685f4b6736d5dce12d51c7bb5f2d8a338d",
   "scripts": {
     "build": "vite build",
     "clean": "premove ./dist ./coverage ./dist-ts",
     "compile": "tsc --build",
     "dev": "tsx watch src/index.ts",
-    "test:eslint": "eslint ./src",
+    "fix": "prettier --write ./src && eslint --fix ./src",
+    "test:eslint": "eslint ./src --max-warnings=0",
+    "test:types": "tsc --noEmit",
     "test:unit": "vitest",
     "test:unit:dev": "pnpm run test:unit --watch"
   }

package/src/__tests__/aiSdkPins.test.ts

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+// The @ai-sdk packages publish many times a day and hard-pin each other to exact
+// versions. A floating range therefore resolves to a release that may be minutes
+// old, and npm's registry metadata is not consistent that fast — a fresh install
+// intermittently fails with ERR_PNPM_NO_MATCHING_VERSION on a transitive @ai-sdk
+// dependency. Downstream consumers install from the registry without a lockfile,
+// so an exact version in a *published* dependency field is what protects them.
+
+// Walk up from the vitest cwd rather than resolving import.meta.url, which vitest
+// serves through its /@fs/ prefix.
+const findRepoRoot = () => {
+  let dir = process.cwd()
+  while (!existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+    const parent = dirname(dir)
+    if (parent === dir) throw new Error('workspace root not found above cwd')
+    dir = parent
+  }
+  return dir
+}
+
+const repoRoot = findRepoRoot()
+const workspaceDirs = ['packages', 'examples']
+const dependencyFields = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+] as const
+
+const isAiSdkPackage = (name: string) =>
+  name === 'ai' || name.startsWith('@ai-sdk/')
+
+const isExactVersion = (range: string) => /^\d+\.\d+\.\d+/.test(range)
+
+const collectPackageJsonPaths = () => {
+  const paths = [join(repoRoot, 'package.json')]
+  for (const dir of workspaceDirs) {
+    for (const entry of readdirSync(join(repoRoot, dir), {
+      withFileTypes: true,
+    })) {
+      if (entry.isDirectory()) {
+        paths.push(join(repoRoot, dir, entry.name, 'package.json'))
+      }
+    }
+  }
+  return paths
+}
+
+const collectAiSdkRanges = () => {
+  const found: { where: string; name: string; range: string }[] = []
+  for (const path of collectPackageJsonPaths()) {
+    let raw: string
+    try {
+      raw = readFileSync(path, 'utf8')
+    } catch {
+      continue
+    }
+    const pkg = JSON.parse(raw) as Record<string, Record<string, string>>
+    for (const field of dependencyFields) {
+      for (const [name, range] of Object.entries(pkg[field] ?? {})) {
+        if (isAiSdkPackage(name)) {
+          found.push({
+            where: `${path.slice(repoRoot.length + 1)} (${field})`,
+            name,
+            range,
+          })
+        }
+      }
+    }
+  }
+  return found
+}
+
+describe('@ai-sdk dependency pins', () => {
+  it('finds the @ai-sdk dependencies it is meant to guard', () => {
+    expect(collectAiSdkRanges().length).toBeGreaterThan(0)
+  })
+
+  it('declares every ai / @ai-sdk dependency as an exact version', () => {
+    const floating = collectAiSdkRanges().filter(
+      ({ range }) => !isExactVersion(range),
+    )
+    expect(
+      floating.map(({ where, name, range }) => `${where}: ${name}@${range}`),
+    ).toEqual([])
+  })
+})

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/appCatalogTypes.ts

@@ -31,10 +31,10 @@ export type ApprovalType = 'none' | 'service' | 'person' | 'other' | 'unknown'
 /**
  * Approval type options for UI display
  */
-export const APPROVAL_TYPES: ReadonlyArray<{
+export const APPROVAL_TYPES: readonly {
   value: ApprovalType
   label: string
-}> = [
+}[] = [
   { value: 'none', label: 'None' },
   { value: 'service', label: 'Service' },
   { value: 'person', label: 'Person' },
@@ -47,10 +47,10 @@ export const APPROVAL_TYPES: ReadonlyArray<{
  */
 export interface BaseApprovalMethod {
   comment?: string
-  roles?: Array<AppRole>
+  roles?: AppRole[]
   approvalPolicy?: string
   postApprovalInstructions?: string
-  seeMoreUrls?: Array<string>
+  seeMoreUrls?: string[]
 }
 
 /**
@@ -152,13 +152,13 @@ export interface AppForCatalog {
   displayName: string
   description?: string
   approvalMethod?: ApprovalMethod
-  teams?: Array<string> // Teams that use this app
+  teams?: string[] // Teams that use this app
   notes?: string
-  tags?: Array<string>
+  tags?: string[]
   appUrl?: string
-  links?: Array<{ url: string; title?: string }>
+  links?: { url: string; title?: string }[]
   iconName?: string
-  screenshotIds?: Array<string>
+  screenshotIds?: string[]
 }
 
 // Derived catalog data returned by backend
@@ -168,6 +168,6 @@ export interface AppCategory {
 }
 
 export interface AppCatalogData {
-  apps: Array<AppForCatalog>
-  categories: Array<AppCategory>
+  apps: AppForCatalog[]
+  categories: AppCategory[]
 }

package/src/index.ts

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

package/src/nullToUndefined.ts

@@ -19,8 +19,8 @@ export type NullToUndefined<T> = T extends null
   ? undefined
   : T extends Primitive | Function | Date | RegExp
     ? T
-    : T extends Array<infer U>
-      ? Array<NullToUndefined<U>>
+    : T extends (infer U)[]
+      ? NullToUndefined<U>[]
       : T extends Map<infer K, infer V>
         ? Map<K, NullToUndefined<V>>
         : T extends Set<infer U>
@@ -33,8 +33,8 @@ export type UndefinedToNull<T> = T extends undefined
   ? null
   : T extends Primitive | Function | Date | RegExp
     ? T
-    : T extends Array<infer U>
-      ? Array<UndefinedToNull<U>>
+    : T extends (infer U)[]
+      ? UndefinedToNull<U>[]
       : T extends Map<infer K, infer V>
         ? Map<K, UndefinedToNull<V>>
         : T extends Set<infer U>

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)
+}