@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/sessrumnir/src/main/omp-fork-points.ts

@@ -0,0 +1,105 @@
+import { createReadStream } from 'fs'
+import { stat } from 'fs/promises'
+import { createInterface } from 'readline'
+import type { ForkPoint } from '../shared/fork-point'
+import { isUserMessageRecord, userMessageText } from './session-metadata'
+
+/**
+ * Fork-point discovery for OMP sessions.
+ *
+ * Pi answers the `get_fork_messages` RPC with the user messages that can be
+ * forked from; OMP removed that command (branching is `branch` + an entry id).
+ * OMP keeps the same v3 session file layout — `{"type":"message","id":…}`
+ * entries with 8-char hex ids — so the GUI reads the candidates straight from
+ * the session file instead.
+ */
+
+/** Byte pattern every user-turn record carries (records are written compact). */
+const USER_ROLE_MARKER = '"role":"user"'
+
+/** Entries kept in the mtime-keyed cache; one per open session is plenty. */
+const FORK_POINTS_CACHE_MAX = 64
+
+/**
+ * Fork candidate on a single session JSONL line: a user message entry that
+ * carries an entry id. Returns null for every other record.
+ */
+export function forkPointFromLine(line: string): ForkPoint | null {
+  // Cheap prefilter: tool results and assistant turns outnumber user turns
+  // roughly twenty to one, and none of them carry the user role marker.
+  if (!line || !line.includes(USER_ROLE_MARKER)) return null
+  let record: unknown
+  try {
+    record = JSON.parse(line)
+  } catch {
+    return null
+  }
+  if (!isUserMessageRecord(record)) return null
+  const id = (record as { id?: unknown }).id
+  if (typeof id !== 'string' || id.length === 0) return null
+  const text = userMessageText(record)
+  if (text === null) return null
+  return { entryId: id, text }
+}
+
+/**
+ * Stream a session file and return its fork candidates in file (chronological)
+ * order. Never throws — an unreadable or malformed file yields an empty list,
+ * matching how the renderer treats a failed `get_fork_messages`.
+ */
+export async function readForkPoints(sessionPath: string): Promise<ForkPoint[]> {
+  let stream
+  try {
+    stream = createReadStream(sessionPath, { encoding: 'utf-8' })
+    const rl = createInterface({ input: stream, crlfDelay: Infinity })
+    const points: ForkPoint[] = []
+    for await (const line of rl) {
+      const point = forkPointFromLine(line)
+      if (point) points.push(point)
+    }
+    return points
+  } catch {
+    return []
+  } finally {
+    stream?.destroy()
+  }
+}
+
+interface ForkPointsCacheEntry {
+  mtimeMs: number
+  size: number
+  points: ForkPoint[]
+}
+
+const forkPointsCache = new Map<string, ForkPointsCacheEntry>()
+
+/**
+ * `readForkPoints` behind an mtime+size check, so reopening the Timeline
+ * between turns costs one `stat` instead of a full re-parse of the session.
+ */
+export async function readForkPointsCached(sessionPath: string): Promise<ForkPoint[]> {
+  let mtimeMs: number
+  let size: number
+  try {
+    ;({ mtimeMs, size } = await stat(sessionPath))
+  } catch {
+    return []
+  }
+  const hit = forkPointsCache.get(sessionPath)
+  if (hit && hit.mtimeMs === mtimeMs && hit.size === size) return hit.points
+
+  const points = await readForkPoints(sessionPath)
+  // Re-insert so eviction order tracks the most recent write, not the first.
+  forkPointsCache.delete(sessionPath)
+  forkPointsCache.set(sessionPath, { mtimeMs, size, points })
+  if (forkPointsCache.size > FORK_POINTS_CACHE_MAX) {
+    const oldest = forkPointsCache.keys().next().value
+    if (oldest !== undefined) forkPointsCache.delete(oldest)
+  }
+  return points
+}
+
+/** Test helper: clear the cache between cases. */
+export function clearForkPointsCache(): void {
+  forkPointsCache.clear()
+}

package/apps/sessrumnir/src/main/omp-plugin-list.test.ts

@@ -0,0 +1,94 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { parseOmpNpmPlugins, parseOmpPluginList } from './omp-plugin-list'
+
+const PLUGINS_DIR = '/home/u/.omp/plugins'
+
+test('parseOmpPluginList handles the empty store', () => {
+  assert.deepEqual(parseOmpPluginList('{"npm":[],"marketplace":[]}', PLUGINS_DIR), [])
+})
+
+test('parseOmpPluginList maps npm rows with their real install path', () => {
+  const output = JSON.stringify({
+    npm: [
+      {
+        name: '@oh-my-pi/example',
+        version: '1.2.3',
+        path: '/home/u/.omp/plugins/node_modules/@oh-my-pi/example',
+        manifest: {},
+        enabledFeatures: [],
+        enabled: true,
+      },
+    ],
+    marketplace: [],
+  })
+  assert.deepEqual(parseOmpPluginList(output, PLUGINS_DIR), [
+    {
+      name: '@oh-my-pi/example',
+      source: '@oh-my-pi/example',
+      type: 'package',
+      version: '1.2.3',
+      path: '/home/u/.omp/plugins/node_modules/@oh-my-pi/example',
+    },
+  ])
+})
+
+test('parseOmpPluginList maps marketplace rows by id (they carry no name)', () => {
+  const output = JSON.stringify({
+    npm: [],
+    marketplace: [{ id: 'reviewer@main-market', scope: 'user', entries: [] }],
+  })
+  assert.deepEqual(parseOmpPluginList(output, PLUGINS_DIR), [
+    {
+      name: 'reviewer@main-market',
+      source: 'reviewer@main-market',
+      type: 'package',
+      version: null,
+      path: PLUGINS_DIR,
+    },
+  ])
+})
+
+test('parseOmpPluginList skips entries without a usable name or id', () => {
+  const output = JSON.stringify({ npm: [{ version: '1.0.0' }, null, 42, 'bare-string', { name: '' }] })
+  assert.deepEqual(parseOmpPluginList(output, PLUGINS_DIR), [])
+})
+
+test('parseOmpPluginList recovers JSON behind CLI warnings', () => {
+  const output = `warning: something\n{"npm":[{"name":"x"}]}\n`
+  assert.deepEqual(parseOmpPluginList(output, PLUGINS_DIR), [
+    { name: 'x', source: 'x', type: 'package', version: null, path: PLUGINS_DIR },
+  ])
+})
+
+test('parseOmpPluginList returns [] on garbage', () => {
+  assert.deepEqual(parseOmpPluginList('not json at all', PLUGINS_DIR), [])
+  assert.deepEqual(parseOmpPluginList('[]', PLUGINS_DIR), [])
+  assert.deepEqual(parseOmpPluginList('', PLUGINS_DIR), [])
+})
+
+test('parseOmpNpmPlugins keeps the runtime state a reinstall resets', () => {
+  const output = JSON.stringify({
+    npm: [
+      { name: 'defaults', version: '0.14.0', enabledFeatures: null, enabled: true },
+      { name: 'picked', version: '1.0.0', enabledFeatures: ['a', 7, 'b'], enabled: false },
+    ],
+    marketplace: [{ id: 'reviewer@main-market', scope: 'user', entries: [] }],
+  })
+  assert.deepEqual(parseOmpNpmPlugins(output), [
+    { name: 'defaults', version: '0.14.0', enabled: true, enabledFeatures: null },
+    { name: 'picked', version: '1.0.0', enabled: false, enabledFeatures: ['a', 'b'] },
+  ])
+})
+
+test('parseOmpNpmPlugins treats a missing enabled flag as enabled and skips nameless rows', () => {
+  const output = `warning: x\n${JSON.stringify({ npm: [{ name: 'x' }, { version: '1.0.0' }, null] })}`
+  assert.deepEqual(parseOmpNpmPlugins(output), [
+    { name: 'x', version: null, enabled: true, enabledFeatures: null },
+  ])
+})
+
+test('parseOmpNpmPlugins returns [] without an npm array', () => {
+  assert.deepEqual(parseOmpNpmPlugins('{"marketplace":[]}'), [])
+  assert.deepEqual(parseOmpNpmPlugins('not json'), [])
+})

package/apps/sessrumnir/src/main/omp-plugin-list.ts

@@ -0,0 +1,103 @@
+import type { InstalledPackage } from '../shared/ipc-contracts'
+
+/**
+ * Parsing for `omp plugin list --json`.
+ *
+ * OMP does not track packages in a settings.json `packages` array the way Pi
+ * does — its plugin store lives in `~/.omp/plugins/` — so the GUI's installed
+ * list comes from the CLI's JSON output: `{ "npm": [...], "marketplace": [...] }`.
+ *
+ * Row shapes as OMP 18 emits them:
+ *  - npm:         `{ name, version, path, manifest, enabledFeatures, enabled }`
+ *  - marketplace: `{ id: "<plugin>@<marketplace>", scope, entries, shadowedBy? }`
+ * Marketplace rows carry no `name`; their `id` is also the spec
+ * `omp plugin uninstall` expects, so it doubles as the row's source.
+ */
+export function parseOmpPluginList(output: string, pluginsDir: string): InstalledPackage[] {
+  const parsed = parseListJson(output)
+  if (!parsed) return []
+
+  const packages: InstalledPackage[] = []
+  for (const entries of Object.values(parsed)) {
+    if (!Array.isArray(entries)) continue
+    for (const entry of entries) {
+      const item = ompPluginEntry(entry, pluginsDir)
+      if (item) packages.push(item)
+    }
+  }
+  return packages
+}
+
+/**
+ * An npm-installed OMP plugin with the runtime state a reinstall resets:
+ * `omp install` re-enables the plugin and replaces its feature selection, so
+ * an update must carry both across. `enabledFeatures` is null when the plugin
+ * runs its default features.
+ */
+export interface OmpNpmPlugin {
+  name: string
+  version: string | null
+  enabled: boolean
+  enabledFeatures: string[] | null
+}
+
+/** The `npm` rows of `omp plugin list --json`; marketplace rows are skipped. */
+export function parseOmpNpmPlugins(output: string): OmpNpmPlugin[] {
+  const parsed = parseListJson(output)
+  const rows = parsed?.npm
+  if (!Array.isArray(rows)) return []
+
+  const plugins: OmpNpmPlugin[] = []
+  for (const row of rows) {
+    if (typeof row !== 'object' || row === null) continue
+    const e = row as Record<string, unknown>
+    const name = nonEmptyString(e.name)
+    if (!name) continue
+    plugins.push({
+      name,
+      version: nonEmptyString(e.version),
+      enabled: e.enabled !== false,
+      enabledFeatures: Array.isArray(e.enabledFeatures)
+        ? e.enabledFeatures.filter((feature): feature is string => typeof feature === 'string')
+        : null,
+    })
+  }
+  return plugins
+}
+
+function parseListJson(output: string): Record<string, unknown> | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(output)
+  } catch {
+    // The CLI may prefix warnings; retry on the outermost JSON object.
+    const start = output.indexOf('{')
+    const end = output.lastIndexOf('}')
+    if (start === -1 || end <= start) return null
+    try {
+      parsed = JSON.parse(output.slice(start, end + 1))
+    } catch {
+      return null
+    }
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return null
+  return parsed as Record<string, unknown>
+}
+
+function ompPluginEntry(entry: unknown, pluginsDir: string): InstalledPackage | null {
+  if (typeof entry !== 'object' || entry === null) return null
+  const e = entry as Record<string, unknown>
+  const name = nonEmptyString(e.name) ?? nonEmptyString(e.id)
+  if (!name) return null
+  return {
+    name,
+    source: name,
+    type: 'package',
+    version: nonEmptyString(e.version) ?? null,
+    path: nonEmptyString(e.path) ?? pluginsDir,
+  }
+}
+
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}

package/apps/sessrumnir/src/main/package-catalog.test.ts

@@ -0,0 +1,157 @@
+import assert from 'node:assert/strict'
+import { test, afterEach } from 'node:test'
+import {
+  parseCatalogHtml,
+  filterCatalog,
+  fetchAllCatalogPackages,
+  fetchPackageCatalog,
+  clearCatalogCache,
+  PAGE_CONCURRENCY,
+} from './package-catalog'
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+function card(opts: {
+  name: string
+  desc?: string
+  author?: string
+  type?: string
+  downloads?: number
+}): string {
+  const { name, desc = '', author = 'someone', type = 'extension', downloads = 100 } = opts
+  return `<article data-package-card="true" data-package-name="${name}" data-package-downloads="${downloads}" data-package-date="1700000000000" data-type="${type}">
+  <p class="packages-desc">${desc}</p>
+  <div class="packages-meta"><span>${author}</span><span>${downloads}/mo</span><span>2 days ago</span></div>
+  <a href="https://www.npmjs.com/package/${name}">npm</a>
+  <a href="https://github.com/${author}/${name}/issues/1">issue</a>
+  <a href="https://github.com/${author}/${name}">repo</a>
+</article>`
+}
+
+function page(cards: string[]): string {
+  return `<html><body>${cards.join('\n')}</body></html>`
+}
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+  clearCatalogCache()
+})
+
+// ─── parseCatalogHtml ────────────────────────────────────────────────────────
+
+test('parseCatalogHtml extracts package fields from a card', () => {
+  const html = page([
+    card({ name: 'pi-ollama-cloud', desc: 'Cloud vision provider', author: 'alice', downloads: 1234 }),
+  ])
+  const [pkg] = parseCatalogHtml(html)
+
+  assert.equal(pkg.name, 'pi-ollama-cloud')
+  assert.equal(pkg.description, 'Cloud vision provider')
+  assert.equal(pkg.author, 'alice')
+  assert.equal(pkg.type, 'extension')
+  assert.equal(pkg.downloads, 1234)
+  assert.equal(pkg.downloadsDisplay, '1234/mo')
+  assert.equal(pkg.npmUrl, 'https://www.npmjs.com/package/pi-ollama-cloud')
+  assert.equal(pkg.installCommand, 'npm:pi-ollama-cloud')
+})
+
+test('parseCatalogHtml prefers the repo link over the issues link', () => {
+  const [pkg] = parseCatalogHtml(page([card({ name: 'pkg', author: 'bob' })]))
+  // The /issues/ URL appears first in the fixture; it must be skipped.
+  assert.equal(pkg.repoUrl, 'https://github.com/bob/pkg')
+})
+
+test('parseCatalogHtml returns [] when there are no cards', () => {
+  assert.deepEqual(parseCatalogHtml('<html><body>nothing here</body></html>'), [])
+})
+
+// ─── filterCatalog ───────────────────────────────────────────────────────────
+
+const SAMPLE = parseCatalogHtml(
+  page([
+    card({ name: 'pi-ollama-cloud', desc: 'Cloud vision provider', author: 'alice' }),
+    card({ name: '@ollama/pi-web-search', desc: 'Web search', author: 'ollama' }),
+    card({ name: 'pi-intercom', desc: 'Intercom integration', author: 'carol' }),
+  ])
+)
+
+test('filterCatalog returns all packages for an empty query', () => {
+  assert.equal(filterCatalog(SAMPLE, undefined).length, 3)
+  assert.equal(filterCatalog(SAMPLE, '   ').length, 3)
+})
+
+test('filterCatalog matches a single token in the name', () => {
+  const result = filterCatalog(SAMPLE, 'intercom')
+  assert.deepEqual(result.map((p) => p.name), ['pi-intercom'])
+})
+
+test('filterCatalog matches multi-word queries across hyphenated names', () => {
+  // "ollama cloud" must match "pi-ollama-cloud" even though the literal
+  // substring "ollama cloud" never appears.
+  const result = filterCatalog(SAMPLE, 'ollama cloud')
+  assert.deepEqual(result.map((p) => p.name), ['pi-ollama-cloud'])
+})
+
+test('filterCatalog is case-insensitive and matches author/description', () => {
+  assert.equal(filterCatalog(SAMPLE, 'OLLAMA').length, 2)
+  assert.deepEqual(filterCatalog(SAMPLE, 'web search').map((p) => p.name), ['@ollama/pi-web-search'])
+})
+
+test('filterCatalog returns [] when no package matches', () => {
+  assert.deepEqual(filterCatalog(SAMPLE, 'nonexistent-xyz'), [])
+})
+
+// ─── fetchAllCatalogPackages (pagination + cache) ─────────────────────────────
+
+const FULL_PAGE = page(Array.from({ length: 50 }, (_, i) => card({ name: `pkg-${i}` })))
+// Distinct names per page so a realistic catalog (unique package names) isn't
+// collapsed by the crawler's name-dedup.
+const fullPageOf = (base: number): string =>
+  page(Array.from({ length: 50 }, (_, i) => card({ name: `pkg-${base}-${i}` })))
+const SHORT_PAGE = page([card({ name: 'pi-ollama-cloud' }), card({ name: 'last-one' })])
+
+function stubPages(pages: Record<number, string>): () => number {
+  let calls = 0
+  globalThis.fetch = (async (url: string | URL) => {
+    calls += 1
+    const pageNum = Number(new URL(String(url)).searchParams.get('page'))
+    const body = pages[pageNum] ?? page([])
+    return { ok: true, text: async () => body } as Response
+  }) as typeof fetch
+  return () => calls
+}
+
+test('fetchAllCatalogPackages crawls in batches and stops after the short page', async () => {
+  const calls = stubPages({ 1: fullPageOf(1), 2: fullPageOf(2), 3: SHORT_PAGE })
+  const packages = await fetchAllCatalogPackages({ force: true })
+
+  // 50 + 50 + 2 unique cards collected. Pages past 3 are fetched concurrently in
+  // the same batch but return empty, and the short page 3 stops further batches.
+  assert.equal(packages.length, 102)
+  assert.ok(calls() >= 3 && calls() <= PAGE_CONCURRENCY, 'stops after the first concurrent batch')
+  assert.ok(packages.some((p) => p.name === 'pi-ollama-cloud'))
+})
+
+test('fetchAllCatalogPackages serves a cached result without refetching', async () => {
+  const calls = stubPages({ 1: SHORT_PAGE })
+  await fetchAllCatalogPackages({ force: true })
+  const callsAfterFirst = calls()
+
+  await fetchAllCatalogPackages()
+  assert.equal(calls(), callsAfterFirst, 'second call must hit the cache')
+})
+
+test('fetchPackageCatalog finds a package that lives beyond the first page', async () => {
+  stubPages({ 1: FULL_PAGE, 2: SHORT_PAGE })
+  const result = await fetchPackageCatalog('ollama cloud')
+  assert.deepEqual(result.map((p) => p.name), ['pi-ollama-cloud'])
+})
+
+test('fetchPackageCatalog returns [] when the network throws', async () => {
+  globalThis.fetch = (async () => {
+    throw new Error('network down')
+  }) as typeof fetch
+  assert.deepEqual(await fetchPackageCatalog('anything'), [])
+})

package/apps/sessrumnir/src/main/package-catalog.ts

@@ -0,0 +1,166 @@
+import type { CatalogPackage } from '../shared/ipc-contracts'
+import { filterCatalog } from '../shared/package-filter'
+
+// Re-exported so existing importers (and tests) keep resolving it from here.
+export { filterCatalog }
+
+// The package catalog at pi.dev/packages is a server-rendered, paginated list
+// with no search endpoint (query params are ignored, /api/* returns 501). To
+// make the whole catalog searchable we scrape every page once, cache it, and
+// filter locally.
+
+const CATALOG_BASE_URL = 'https://pi.dev/packages'
+// The server renders up to this many package cards per page; a short page marks
+// the end of the catalog.
+const PAGE_SIZE = 50
+// Safety cap so a server change (e.g. always-full pages) cannot loop forever.
+const MAX_PAGES = 40
+// Pages fetched concurrently per batch (crawl stops at the first short page).
+export const PAGE_CONCURRENCY = 8
+// Re-scrape at most this often; search fires on every keystroke, so without a
+// cache each keystroke would re-crawl every page.
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+interface CatalogCache {
+  packages: CatalogPackage[]
+  fetchedAt: number
+}
+
+let catalogCache: CatalogCache | null = null
+// Shared in-flight crawl so concurrent callers (e.g. the startup prefetch and a
+// user opening the Catalog tab) await the same request instead of each crawling.
+let inFlightCrawl: Promise<CatalogPackage[]> | null = null
+
+// Parse the package cards out of a single rendered catalog page. Pure so it can
+// be tested against captured HTML without network access.
+export function parseCatalogHtml(html: string): CatalogPackage[] {
+  const packages: CatalogPackage[] = []
+  const articleRegex = /<article[^>]*data-package-card="true"[^>]*>[\s\S]*?<\/article>/g
+  let articleMatch: RegExpExecArray | null
+
+  while ((articleMatch = articleRegex.exec(html)) !== null) {
+    const article = articleMatch[0]
+
+    const nameMatch = article.match(/data-package-name="([^"]+)"/)
+    if (!nameMatch) continue
+    const name = nameMatch[1]
+
+    const downloadsRawMatch = article.match(/data-package-downloads="([^"]+)"/)
+    const dateMatch = article.match(/data-package-date="([^"]+)"/)
+
+    const descMatch = article.match(/<p class="packages-desc">([^<]+)<\/p>/)
+    const description = descMatch ? descMatch[1].trim() : ''
+
+    // packages-meta holds 3 spans: author, downloads/mo display, time-ago
+    const metaMatch = article.match(/<div class="packages-meta">([\s\S]*?)<\/div>/)
+    const metaSpans = metaMatch
+      ? [...metaMatch[1].matchAll(/<span>([^<]*)<\/span>/g)].map((m) => m[1])
+      : []
+    const author = metaSpans[0] ?? ''
+    const downloadsDisplay = metaSpans[1] ?? ''
+
+    const typeMatch = article.match(/data-type="([^"]+)"/)
+    const type = typeMatch ? typeMatch[1] : 'package'
+
+    const npmMatch = article.match(/href="(https:\/\/www\.npmjs\.com\/package\/[^"]+)"/)
+    const npmUrl = npmMatch ? npmMatch[1] : null
+
+    // Repo link is a github.com URL that is not a /issues/ link
+    const githubMatches = [...article.matchAll(/href="(https:\/\/github\.com\/[^"]+)"/g)]
+    const repoUrl = githubMatches.map((m) => m[1]).find((u) => !u.includes('/issues/')) ?? null
+
+    const downloads = downloadsRawMatch ? parseInt(downloadsRawMatch[1], 10) : 0
+    const updatedAt = dateMatch ? new Date(parseInt(dateMatch[1], 10)).toISOString() : ''
+
+    packages.push({
+      name,
+      description,
+      author,
+      type,
+      downloads,
+      downloadsDisplay,
+      updatedAt,
+      npmUrl,
+      repoUrl,
+      installCommand: `npm:${name}`,
+    })
+  }
+
+  return packages
+}
+
+async function fetchCatalogPage(page: number): Promise<CatalogPackage[]> {
+  const response = await fetch(`${CATALOG_BASE_URL}?page=${page}`)
+  if (!response.ok) return []
+  return parseCatalogHtml(await response.text())
+}
+
+// Crawl catalog pages in concurrent batches, stopping once a short page marks
+// the end of the catalog.
+async function crawlAllPages(): Promise<CatalogPackage[]> {
+  // Dedupe by name: batching may request a few pages past the end, and some
+  // paginated servers clamp out-of-range pages to a valid one — deduping keeps
+  // any such repeats out of the catalog. Preserves first-seen (crawl) order.
+  const byName = new Map<string, CatalogPackage>()
+  let nextPage = 1
+  let reachedEnd = false
+
+  while (!reachedEnd && nextPage <= MAX_PAGES) {
+    const batch: number[] = []
+    for (let i = 0; i < PAGE_CONCURRENCY && nextPage <= MAX_PAGES; i++) {
+      batch.push(nextPage++)
+    }
+    // Promise.all preserves order, so pages are merged in sequence.
+    const pages = await Promise.all(batch.map(fetchCatalogPage))
+    for (const pagePackages of pages) {
+      for (const pkg of pagePackages) {
+        if (!byName.has(pkg.name)) byName.set(pkg.name, pkg)
+      }
+      if (pagePackages.length < PAGE_SIZE) reachedEnd = true
+    }
+  }
+
+  return [...byName.values()]
+}
+
+// Crawl every catalog page and cache the result. Concurrent callers share one
+// in-flight crawl. Exposed so the cache can be primed (e.g. a startup prefetch).
+export async function fetchAllCatalogPackages(
+  options?: { force?: boolean }
+): Promise<CatalogPackage[]> {
+  if (
+    !options?.force &&
+    catalogCache &&
+    Date.now() - catalogCache.fetchedAt < CACHE_TTL_MS
+  ) {
+    return catalogCache.packages
+  }
+
+  if (!inFlightCrawl) {
+    inFlightCrawl = crawlAllPages()
+      .then((packages) => {
+        catalogCache = { packages, fetchedAt: Date.now() }
+        return packages
+      })
+      .finally(() => {
+        inFlightCrawl = null
+      })
+  }
+  return inFlightCrawl
+}
+
+// Reset the in-memory cache (test seam).
+export function clearCatalogCache(): void {
+  catalogCache = null
+  inFlightCrawl = null
+}
+
+// Fetch the full catalog (cached) and apply the search filter locally.
+export async function fetchPackageCatalog(query?: string): Promise<CatalogPackage[]> {
+  try {
+    const packages = await fetchAllCatalogPackages()
+    return filterCatalog(packages, query)
+  } catch {
+    return []
+  }
+}