@prata.ma/anvil-search

Search and indexing runtime and CLI for Anvil workspaces.

Overview

@prata.ma/anvil-search is Anvil's package boundary for local search indexing and retrieval over derived content: canonical session projections emitted by @prata.ma/anvil-sync and reserved markdown collections from Anvil-managed workspaces. It wraps qmd behind Anvil-owned collection naming, refresh helpers, and search functions so callers do not own raw backend setup.

The current package surface focuses on:

• deterministic <workspace-id>:<collection> collection naming
• XDG-rooted local index storage
• projection indexing for summary and transcript
• reserved workspace collection indexing for state, forge, smith, catalog, lab, core, package, and service
• qmd-backed hybrid, BM25, and vector search
• indexed document retrieval by qmd-style path or docid
• a thin standalone anvil-search CLI over the same helpers

Usage

Library

import {
  getIndexedDocument,
  indexWorkspaceCollection,
  indexWorkspaceSummaries,
  searchAll,
} from '@prata.ma/anvil-search'

await indexWorkspaceSummaries({ workspaceId: 'anvil' })
await indexWorkspaceCollection({
  collection: 'package',
  rootPath: './@packages',
  workspaceId: 'anvil',
})

const hits = await searchAll({
  query: 'workspace roadmap',
  workspaceId: 'anvil',
})

const document = await getIndexedDocument({
  includeBody: true,
  pathOrDocid: hits[0]!.path,
})

CLI

anvil-search paths
anvil-search index summary -w anvil
anvil-search index transcript -w anvil
anvil-search index package -w anvil
anvil-search search -w anvil "workspace roadmap"
anvil-search search package -w anvil "anvil search"
anvil-search search state -w anvil --via bm25 "release posture"
anvil-search search package -w anvil --via vector "search runtime"

--workspace identifies the workspace and has -w as a short alias. The older --workspace-id form is accepted by the CLI as a temporary compatibility path.

Collections

Collection names use this stable format:

<workspace-id>:<suffix>

Reserved suffixes are:

• summary - session summary projections from @prata.ma/anvil-sync
• transcript - session transcript projections from @prata.ma/anvil-sync
• state - workspace State root, from anvil.yaml state.root
• forge - workspace Forge/product root, from anvil.yaml forge.root
• smith - workspace Smith/system root, from anvil.yaml smith.root
• catalog - @catalog
• lab - @lab
• core - @core
• package - @packages
• service - @services

Custom collection keys are intentionally deferred. The CLI resolves reserved roots from the nearest anvil.yaml where applicable and fails specific indexing requests when a requested reserved root does not exist.

Search

anvil-search search without a collection searches all reserved collections for the workspace. A collection subcommand narrows the query to one collection.

Search defaults to qmd's hybrid query path when --via is omitted. Explicit --via values are:

• bm25 - qmd full-text/BM25 keyword search through searchLex
• vector - qmd vector similarity search through searchVector

The default hybrid path delegates to qmd's combined query expansion, retrieval, chunk selection, and reranking pipeline.

Default CLI hits are intentionally compact:

{
  "collection": "package",
  "via": "hybrid",
  "score": 0.82,
  "path": "qmd://anvil:package/anvil-search/README.md",
  "title": "@prata.ma/anvil-search",
  "docid": "500ea2",
  "context": null,
  "snippet": "@@ -7,4 @@ (6 before, 68 after)\nSearch and indexing runtime and CLI for Anvil workspaces..."
}

path is the qmd-style retrieval handle and replaces separate display, file, and virtual path fields in CLI output.

Development

Run package-local checks while working in @packages/anvil-search:

pnpm --filter @prata.ma/anvil-search build
pnpm --filter @prata.ma/anvil-search lint
pnpm --filter @prata.ma/anvil-search test
pnpm --filter @prata.ma/anvil-search test:type

The current tests cover deterministic collection naming, projection indexing, reserved collection indexing, scoped search, snippets, qmd-style paths, indexed document retrieval, and the thin command-runner path.

Notes

• Search storage is derived and refreshable; canonical session state remains in @prata.ma/anvil-sync.
• qmd is the backend implementation detail, not the public package contract.
• Runtime tests require a usable local better-sqlite3 native binding because qmd depends on it under the current Node path.