@strav/search 0.4.31 → 1.0.0-alpha.31

package/package.json

@@ -1,32 +1,30 @@
 {
   "name": "@strav/search",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.31",
+  "description": "Strav search module — unified full-text search abstraction over Meilisearch, Typesense, and Postgres FTS, plus an in-process Memory driver. Ships a `searchable()` Repository mixin and console commands.",
   "type": "module",
-  "description": "Full-text search for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts"
-  },
-  "strav": {
-    "commands": "src/commands"
+    ".": "./src/index.ts"
   },
   "files": [
-    "src/",
-    "stubs/",
-    "package.json",
-    "tsconfig.json"
+    "src",
+    "README.md"
   ],
-  "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/database": "0.4.31",
-    "@strav/cli": "0.4.31"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
+  "dependencies": {
+    "@strav/cli": "1.0.0-alpha.31",
+    "@strav/database": "1.0.0-alpha.31",
+    "@strav/kernel": "1.0.0-alpha.31"
+  },
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
   },
-  "devDependencies": {
-    "commander": "^14.0.3"
-  }
+  "devDependencies": null
 }

package/src/console/index.ts

@@ -0,0 +1,5 @@
+export { SearchConsoleProvider } from './search_console_provider.ts'
+export { SearchFlush } from './search_flush.ts'
+export { SearchImport } from './search_import.ts'
+export { SearchList } from './search_list.ts'
+export { SearchReindex } from './search_reindex.ts'

package/src/console/search_console_provider.ts

@@ -0,0 +1,20 @@
+/**
+ * `SearchConsoleProvider` — declares the search console commands.
+ *
+ * Apps add it to `bootstrap/providers.ts` alongside
+ * `SearchProvider`. Separate provider (mirrors
+ * `RagConsoleProvider` and `QueueConsoleProvider`) so apps
+ * that don't use the CLI don't pay the cost of resolving the
+ * commands at boot.
+ */
+
+import { ConsoleProvider } from '@strav/cli'
+import { SearchFlush } from './search_flush.ts'
+import { SearchImport } from './search_import.ts'
+import { SearchList } from './search_list.ts'
+import { SearchReindex } from './search_reindex.ts'
+
+export class SearchConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.search'
+  override readonly commands = [SearchFlush, SearchImport, SearchList, SearchReindex] as const
+}

package/src/console/search_flush.ts

@@ -0,0 +1,49 @@
+/**
+ * `bun strav search:flush <index> [--driver=name] [--force]` —
+ * drop every document in an index on the active (or named)
+ * search engine.
+ *
+ * Use cases:
+ *
+ *   - Wiping a corrupted index before re-import.
+ *   - Cleaning up a dev / staging environment.
+ *   - Recovering after a settings change.
+ *
+ * The command confirms before running unless `--force` is set.
+ * Doesn't touch the source data — apps re-import afterward via
+ * `search:import` (or `repo.importAll()` in their own code).
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { SearchManager } from '../search_manager.ts'
+
+export class SearchFlush extends Command {
+  static signature = 'search:flush {index} {--driver=} {--force}'
+  static description =
+    'Delete every document in an index (on the active or --driver= named engine).'
+  static providers = ['config', 'logger', 'search']
+
+  override async execute({ args, flags }: ExecuteArgs): Promise<number> {
+    const index = args.index as string
+    const driverName =
+      typeof flags.driver === 'string' && flags.driver.length > 0 ? flags.driver : undefined
+
+    const manager = this.app.resolve(SearchManager)
+    const fullIndex = manager.indexName(index)
+    const driverLabel = driverName ?? manager.config.default
+
+    if (flags.force !== true) {
+      const ok = await this.confirm(
+        `Delete every document in index "${fullIndex}" on driver "${driverLabel}"? This is irreversible.`,
+      )
+      if (!ok) {
+        this.info('Aborted.')
+        return ExitCode.Success
+      }
+    }
+
+    await manager.engine(driverName).flush(fullIndex)
+    this.success(`Flushed index "${fullIndex}" on driver "${driverLabel}".`)
+    return ExitCode.Success
+  }
+}

package/src/console/search_import.ts

@@ -0,0 +1,103 @@
+/**
+ * `bun strav search:import {name?} [--all] [--batch=500]` —
+ * walk a registered searchable repository and upsert every row
+ * into its search index.
+ *
+ * Apps register repos at boot:
+ *
+ *   const registry = app.resolve(SearchableRegistry)
+ *   registry.register('articles', ArticleRepository)
+ *
+ * Then:
+ *
+ *   bun strav search:import articles          # one repo
+ *   bun strav search:import --all             # every registered repo
+ *
+ * The repo class must implement `importAll(batchSize?)` and
+ * `createIndex()` — the `searchable()` mixin provides both. The
+ * command calls `createIndex()` first so a fresh deploy doesn't
+ * have to remember to run it separately.
+ *
+ * Long-running on large corpora — apps that need cron-driven or
+ * queued imports ship a custom command pointing at the same
+ * `importAll` method.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { SearchError } from '../search_error.ts'
+import { SearchableRegistry } from '../searchable_registry.ts'
+
+export class SearchImport extends Command {
+  static signature = 'search:import {name?} {--all} {--batch=500}'
+  static description =
+    'Re-import one registered searchable repository (or every one with --all).'
+  static providers = ['config', 'logger', 'search', 'database']
+
+  override async execute({ args, flags }: ExecuteArgs): Promise<number> {
+    const registry = this.app.resolve(SearchableRegistry)
+    const batchSize = parseBatch(flags.batch)
+
+    if (flags.all === true) {
+      const names = registry.names()
+      if (names.length === 0) {
+        this.warn(
+          'No searchables registered. Call `registry.register(name, Repo)` from a service provider first.',
+        )
+        return ExitCode.Success
+      }
+      let total = 0
+      for (const name of names) {
+        const processed = await this.importOne(registry, name, batchSize)
+        total += processed
+      }
+      this.success(
+        `Imported ${total} rows across ${names.length} repositor${names.length === 1 ? 'y' : 'ies'}.`,
+      )
+      return ExitCode.Success
+    }
+
+    const name = args.name
+    if (typeof name !== 'string' || name.length === 0) {
+      this.error(
+        'search:import requires a repository name, or --all to import every registered repository.',
+      )
+      this.info(`Registered: ${registry.names().join(', ') || '(none)'}`)
+      return ExitCode.UsageError
+    }
+
+    try {
+      const processed = await this.importOne(registry, name, batchSize)
+      this.success(`Imported ${processed} rows in "${name}".`)
+      return ExitCode.Success
+    } catch (err) {
+      if (err instanceof SearchError) {
+        this.error(err.message)
+        this.info(`Registered: ${registry.names().join(', ') || '(none)'}`)
+        return ExitCode.GenericFailure
+      }
+      throw err
+    }
+  }
+
+  private async importOne(
+    registry: SearchableRegistry,
+    name: string,
+    batchSize: number,
+  ): Promise<number> {
+    this.info(`Importing "${name}"…`)
+    const repo = this.app.resolve(registry.resolve(name))
+    await repo.createIndex()
+    const processed = await repo.importAll(batchSize)
+    this.info(`  ${processed} rows.`)
+    return processed
+  }
+}
+
+function parseBatch(raw: unknown): number {
+  if (typeof raw === 'number' && raw > 0) return Math.floor(raw)
+  if (typeof raw === 'string') {
+    const n = Number.parseInt(raw, 10)
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  return 500
+}

package/src/console/search_list.ts

@@ -0,0 +1,46 @@
+/**
+ * `bun strav search:list` — print the configured search drivers
+ * + registered searchable repositories.
+ *
+ * Diagnostic only — no mutations. Useful for verifying that
+ * `config/search.ts` parses correctly and that the registered
+ * driver / repository names match what's expected.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { SearchManager } from '../search_manager.ts'
+import { SearchableRegistry } from '../searchable_registry.ts'
+
+export class SearchList extends Command {
+  static signature = 'search:list'
+  static description = 'List configured search drivers + registered searchable repositories.'
+  static providers = ['config', 'logger', 'search']
+
+  override async execute(_args: ExecuteArgs): Promise<number> {
+    const manager = this.app.resolve(SearchManager)
+    const registry = this.app.resolve(SearchableRegistry)
+    const config = manager.config
+
+    this.info(`Default driver: ${config.default}`)
+    if (config.prefix) this.info(`Index prefix:   ${config.prefix}`)
+
+    this.info('')
+    this.info('Drivers:')
+    for (const [name, driver] of Object.entries(config.drivers)) {
+      const flag = name === config.default ? ' (default)' : ''
+      this.info(`  ${name}${flag}: driver=${driver.driver}`)
+    }
+
+    this.info('')
+    const names = registry.names()
+    if (names.length === 0) {
+      this.info('Registered searchables: (none)')
+      this.info(
+        '  Register repositories at boot: `app.resolve(SearchableRegistry).register(name, Repo)`',
+      )
+    } else {
+      this.info(`Registered searchables: ${names.join(', ')}`)
+    }
+    return ExitCode.Success
+  }
+}

package/src/console/search_reindex.ts

@@ -0,0 +1,94 @@
+/**
+ * `bun strav search:reindex {name?} [--all] [--batch=500]` —
+ * flush a registered searchable repository's index, then walk
+ * every row and re-upsert.
+ *
+ * Use after changing `searchableSettings()` (e.g., adding a new
+ * `searchableAttribute` or `filterableAttribute`) — for the
+ * Postgres FTS driver, existing rows keep their old `fts` until
+ * they're rewritten. The combined "flush + import" is what apps
+ * usually want; pure imports are available via `search:import`.
+ *
+ * Both `flushIndex()` + `importAll()` come from the
+ * `searchable()` mixin.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { SearchError } from '../search_error.ts'
+import { SearchableRegistry } from '../searchable_registry.ts'
+
+export class SearchReindex extends Command {
+  static signature = 'search:reindex {name?} {--all} {--batch=500}'
+  static description =
+    'Flush + re-import one registered searchable repository (or every one with --all).'
+  static providers = ['config', 'logger', 'search', 'database']
+
+  override async execute({ args, flags }: ExecuteArgs): Promise<number> {
+    const registry = this.app.resolve(SearchableRegistry)
+    const batchSize = parseBatch(flags.batch)
+
+    if (flags.all === true) {
+      const names = registry.names()
+      if (names.length === 0) {
+        this.warn(
+          'No searchables registered. Call `registry.register(name, Repo)` from a service provider first.',
+        )
+        return ExitCode.Success
+      }
+      let total = 0
+      for (const name of names) {
+        const processed = await this.reindexOne(registry, name, batchSize)
+        total += processed
+      }
+      this.success(
+        `Re-indexed ${total} rows across ${names.length} repositor${names.length === 1 ? 'y' : 'ies'}.`,
+      )
+      return ExitCode.Success
+    }
+
+    const name = args.name
+    if (typeof name !== 'string' || name.length === 0) {
+      this.error(
+        'search:reindex requires a repository name, or --all to re-index every registered repository.',
+      )
+      this.info(`Registered: ${registry.names().join(', ') || '(none)'}`)
+      return ExitCode.UsageError
+    }
+
+    try {
+      const processed = await this.reindexOne(registry, name, batchSize)
+      this.success(`Re-indexed ${processed} rows in "${name}".`)
+      return ExitCode.Success
+    } catch (err) {
+      if (err instanceof SearchError) {
+        this.error(err.message)
+        this.info(`Registered: ${registry.names().join(', ') || '(none)'}`)
+        return ExitCode.GenericFailure
+      }
+      throw err
+    }
+  }
+
+  private async reindexOne(
+    registry: SearchableRegistry,
+    name: string,
+    batchSize: number,
+  ): Promise<number> {
+    this.info(`Re-indexing "${name}"…`)
+    const repo = this.app.resolve(registry.resolve(name))
+    await repo.createIndex()
+    await repo.flushIndex()
+    const processed = await repo.importAll(batchSize)
+    this.info(`  ${processed} rows.`)
+    return processed
+  }
+}
+
+function parseBatch(raw: unknown): number {
+  if (typeof raw === 'number' && raw > 0) return Math.floor(raw)
+  if (typeof raw === 'string') {
+    const n = Number.parseInt(raw, 10)
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  return 500
+}

package/src/drivers/meilisearch/meilisearch_driver.ts

@@ -0,0 +1,304 @@
+/**
+ * `MeilisearchDriver` — REST client for [Meilisearch](https://meilisearch.com).
+ *
+ * Speaks the v1 HTTP API via raw `fetch()` — no `meilisearch-js`
+ * SDK dependency. The driver mirrors the engine contract: every
+ * write awaits the underlying Meili task before returning so
+ * subsequent reads see the result. Apps that want fire-and-forget
+ * indexing drop down to the raw engine and inspect `taskUid`s
+ * themselves.
+ *
+ * Config (under `config.search.drivers.<name>`):
+ *
+ * ```ts
+ * meili: {
+ *   driver: 'meilisearch',
+ *   host: 'http://localhost:7700',       // or split host/port/protocol
+ *   apiKey: env('MEILI_KEY'),
+ *   taskTimeoutMs: 10_000,               // optional, defaults 10s
+ *   taskPollIntervalMs: 25,              // optional, defaults 25ms
+ *   awaitTasks: true,                    // optional, defaults true
+ * }
+ * ```
+ *
+ * Error mapping:
+ *
+ *   - `404` on writes / reads → `IndexNotFoundError`.
+ *   - All other non-2xx + task `failed` → `SearchQueryError`
+ *     with the Meili payload on `cause`.
+ *
+ * @see https://www.meilisearch.com/docs/reference/api/overview
+ */
+
+import { IndexNotFoundError, SearchQueryError } from '../../search_error.ts'
+import type { SearchEngine } from '../../search_engine.ts'
+import type {
+  DriverConfig,
+  IndexSettings,
+  SearchDocument,
+  SearchHit,
+  SearchOptions,
+  SearchResult,
+} from '../../types.ts'
+
+interface TaskResponse {
+  taskUid?: number
+  uid?: number
+  status?: string
+}
+
+interface TaskDetail {
+  uid: number
+  status: 'enqueued' | 'processing' | 'succeeded' | 'failed' | 'canceled'
+  error?: unknown
+}
+
+export class MeilisearchDriver implements SearchEngine {
+  readonly name = 'meilisearch'
+
+  private readonly baseUrl: string
+  private readonly apiKey: string
+  private readonly awaitTasks: boolean
+  private readonly taskTimeoutMs: number
+  private readonly taskPollIntervalMs: number
+
+  constructor(config: DriverConfig) {
+    this.baseUrl = resolveBaseUrl(config)
+    this.apiKey = typeof config.apiKey === 'string' ? config.apiKey : ''
+    this.awaitTasks = config.awaitTasks !== false
+    this.taskTimeoutMs = typeof config.taskTimeoutMs === 'number' ? config.taskTimeoutMs : 10_000
+    this.taskPollIntervalMs =
+      typeof config.taskPollIntervalMs === 'number' ? config.taskPollIntervalMs : 25
+  }
+
+  // ─── Index lifecycle ────────────────────────────────────────────────────
+
+  async createIndex(index: string, settings: IndexSettings = {}): Promise<void> {
+    // Meili's `POST /indexes` errors when the index already exists.
+    // We swallow the conflict so `createIndex` stays idempotent.
+    const created = await this.request<TaskResponse>('POST', '/indexes', {
+      body: { uid: index, primaryKey: settings.primaryKey ?? 'id' },
+      acceptStatuses: [409],
+    })
+    if (created && typeof created.taskUid === 'number') await this.awaitTask(created.taskUid)
+
+    const payload: Record<string, unknown> = {}
+    if (settings.searchableAttributes) payload.searchableAttributes = settings.searchableAttributes
+    if (settings.displayedAttributes) payload.displayedAttributes = settings.displayedAttributes
+    if (settings.filterableAttributes) payload.filterableAttributes = settings.filterableAttributes
+    if (settings.sortableAttributes) payload.sortableAttributes = settings.sortableAttributes
+
+    if (Object.keys(payload).length === 0) return
+    const task = await this.request<TaskResponse>(
+      'PATCH',
+      `/indexes/${encodeURIComponent(index)}/settings`,
+      { body: payload },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  async deleteIndex(index: string): Promise<void> {
+    const task = await this.request<TaskResponse>(
+      'DELETE',
+      `/indexes/${encodeURIComponent(index)}`,
+      { acceptStatuses: [404] },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  async flush(index: string): Promise<void> {
+    const task = await this.request<TaskResponse>(
+      'DELETE',
+      `/indexes/${encodeURIComponent(index)}/documents`,
+      { acceptStatuses: [404] },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  // ─── Writes ─────────────────────────────────────────────────────────────
+
+  async upsert(
+    index: string,
+    id: string | number,
+    document: Record<string, unknown>,
+  ): Promise<void> {
+    const task = await this.request<TaskResponse>(
+      'POST',
+      `/indexes/${encodeURIComponent(index)}/documents`,
+      { body: [{ id, ...document }] },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  async upsertMany(index: string, documents: readonly SearchDocument[]): Promise<void> {
+    if (documents.length === 0) return
+    const task = await this.request<TaskResponse>(
+      'POST',
+      `/indexes/${encodeURIComponent(index)}/documents`,
+      { body: documents },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  async delete(index: string, id: string | number): Promise<void> {
+    const task = await this.request<TaskResponse>(
+      'DELETE',
+      `/indexes/${encodeURIComponent(index)}/documents/${encodeURIComponent(String(id))}`,
+      { acceptStatuses: [404] },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  async deleteMany(index: string, ids: readonly (string | number)[]): Promise<void> {
+    if (ids.length === 0) return
+    const task = await this.request<TaskResponse>(
+      'POST',
+      `/indexes/${encodeURIComponent(index)}/documents/delete-batch`,
+      { body: ids },
+    )
+    if (task && typeof task.taskUid === 'number') await this.awaitTask(task.taskUid)
+  }
+
+  // ─── Reads ──────────────────────────────────────────────────────────────
+
+  async search(index: string, query: string, options: SearchOptions = {}): Promise<SearchResult> {
+    const perPage = options.perPage ?? 20
+    const page = options.page ?? 1
+
+    const body: Record<string, unknown> = {
+      q: query,
+      limit: perPage,
+      offset: (page - 1) * perPage,
+    }
+    if (options.filter !== undefined) {
+      if (typeof options.filter !== 'object' || options.filter === null || Array.isArray(options.filter)) {
+        throw new SearchQueryError(
+          'MeilisearchDriver: `filter` must be a flat key/value object. Engine-native strings are not portable.',
+        )
+      }
+      body.filter = buildMeiliFilter(options.filter)
+    }
+    if (options.sort) body.sort = options.sort
+    if (options.attributesToRetrieve) body.attributesToRetrieve = options.attributesToRetrieve
+    if (options.attributesToHighlight) body.attributesToHighlight = options.attributesToHighlight
+
+    const data = await this.request<{
+      hits?: Array<Record<string, unknown> & { _formatted?: Record<string, string> }>
+      estimatedTotalHits?: number
+      totalHits?: number
+      processingTimeMs?: number
+    }>('POST', `/indexes/${encodeURIComponent(index)}/search`, { body })
+
+    const hits: SearchHit[] = (data?.hits ?? []).map((hit) => {
+      const { _formatted, ...document } = hit
+      const out: SearchHit = { document }
+      if (_formatted) out.highlights = _formatted
+      return out
+    })
+
+    return {
+      hits,
+      totalHits: data?.estimatedTotalHits ?? data?.totalHits ?? 0,
+      page,
+      perPage,
+      ...(typeof data?.processingTimeMs === 'number' ? { processingTimeMs: data.processingTimeMs } : {}),
+    }
+  }
+
+  // ─── HTTP / task polling ───────────────────────────────────────────────
+
+  private async awaitTask(uid: number): Promise<void> {
+    if (!this.awaitTasks) return
+    const deadline = Date.now() + this.taskTimeoutMs
+    while (true) {
+      const task = await this.request<TaskDetail>('GET', `/tasks/${uid}`, {})
+      if (!task) throw new SearchQueryError(`MeilisearchDriver: task ${uid} returned no payload.`)
+      if (task.status === 'succeeded') return
+      if (task.status === 'failed' || task.status === 'canceled') {
+        throw new SearchQueryError(`MeilisearchDriver: task ${uid} ${task.status}.`, {
+          context: { uid, status: task.status },
+          cause: task.error,
+        })
+      }
+      if (Date.now() > deadline) {
+        throw new SearchQueryError(
+          `MeilisearchDriver: task ${uid} did not finish within ${this.taskTimeoutMs}ms.`,
+          { context: { uid, status: task.status } },
+        )
+      }
+      await sleep(this.taskPollIntervalMs)
+    }
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    options: { body?: unknown; acceptStatuses?: number[] } = {},
+  ): Promise<T | null> {
+    const headers: Record<string, string> = { 'content-type': 'application/json' }
+    if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`
+
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    })
+
+    if (response.ok || options.acceptStatuses?.includes(response.status)) {
+      if (response.status === 204 || response.headers.get('content-length') === '0') return null
+      const text = await response.text()
+      return text.length === 0 ? null : (JSON.parse(text) as T)
+    }
+
+    const text = await response.text()
+    const payload = safeJson(text)
+    if (response.status === 404) {
+      const index = extractIndexName(path)
+      throw new IndexNotFoundError(index ?? '<unknown>', this.name)
+    }
+    throw new SearchQueryError(
+      `MeilisearchDriver: ${method} ${path} returned ${response.status}.`,
+      { context: { status: response.status, body: payload ?? text }, cause: payload ?? text },
+    )
+  }
+}
+
+function resolveBaseUrl(config: DriverConfig): string {
+  // Accept either a complete `host` URL or split protocol/host/port.
+  const host = typeof config.host === 'string' ? config.host : 'localhost'
+  if (host.startsWith('http://') || host.startsWith('https://')) {
+    return host.replace(/\/+$/, '')
+  }
+  const protocol = typeof config.protocol === 'string' ? config.protocol : 'http'
+  const port = typeof config.port === 'number' ? config.port : 7700
+  return `${protocol}://${host}:${port}`
+}
+
+function buildMeiliFilter(filter: Record<string, unknown>): string {
+  return Object.entries(filter)
+    .map(([key, value]) => {
+      if (Array.isArray(value)) {
+        return `${key} IN [${value.map((v) => JSON.stringify(v)).join(', ')}]`
+      }
+      return `${key} = ${JSON.stringify(value)}`
+    })
+    .join(' AND ')
+}
+
+function extractIndexName(path: string): string | undefined {
+  const match = /\/indexes\/([^/?]+)/.exec(path)
+  return match ? decodeURIComponent(match[1]!) : undefined
+}
+
+function safeJson(text: string): unknown {
+  if (text.length === 0) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}