Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,26 @@
{
"name": "@toolctrl/search",
"version": "0.0.0",
"private": true,
"type": "module",
"sideEffects": false,
"exports": {
".": "./src/index.ts",
"./schemas": "./src/schemas/index.ts",
"./testing": "./src/testing.ts"
},
"scripts": {
"build": "pnpm run typecheck",
"test": "vitest run src",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"meilisearch": "0.45.0",
"zod": "^3.23.8"
},
"devDependencies": {
"@types/node": "^25.0.0",
"typescript": "^5.3.2",
"vitest": "^3.2.4"
}
}
@@ -0,0 +1,46 @@
import { describe, expect, it } from "vitest";
import { createSearchClient } from "./client.js";
import { createInMemoryMeili } from "./testing.js";
describe("createSearchClient", () => {
it("rejects empty url", () => {
expect(() => createSearchClient({ url: "", meiliFactory: createInMemoryMeili().factory })).toThrow(/url/);
});
it("exposes a tenant-agnostic index handle that supports ensure/upsert/search/delete", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const handle = client.index<{ id: string; tenantId: string; title: string }>("kb-articles");
await handle.ensure({
primaryKey: "id",
settings: { searchableAttributes: ["title"], filterableAttributes: ["tenantId"] },
});
await handle.upsert([
{ id: "a", tenantId: "t1", title: "Onboarding" },
{ id: "b", tenantId: "t2", title: "Onboarding" },
]);
const results = await handle.search("Onboarding", { filter: 'tenantId = "t1"', limit: 10 });
expect(results.hits.map((hit) => hit.document.id)).toEqual(["a"]);
expect(results.estimatedTotalHits).toBe(1);
await handle.delete(["a"]);
const after = await handle.search("Onboarding", { filter: 'tenantId = "t1"', limit: 10 });
expect(after.hits).toHaveLength(0);
expect(state.indexes.get("kb-articles")?.settings).toMatchObject({ searchableAttributes: ["title"] });
});
it("returns health = available from a healthy backend", async () => {
const { factory } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(client.health()).resolves.toEqual({ status: "available" });
});
it("reports unavailable when backend reports another status", async () => {
const { factory } = createInMemoryMeili({ healthStatus: "unavailable" });
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(client.health()).resolves.toEqual({ status: "unavailable" });
});
});
@@ -0,0 +1,234 @@
/**
* Search client adapter.
*
* Keeps the raw Meilisearch SDK behind an interface so the rest of the
* package (and the worker indexer) can swap in fakes for tests and so the
* domain code never holds a reference to the unauthenticated client.
*
* Only the surface area we actually need is exposed; callers that want
* additional Meilisearch features must extend this adapter through a
* code-reviewed PR.
*/
import { createRequire } from "node:module";
const requireFromHere = createRequire(import.meta.url);
export type SearchDocument = Record<string, unknown> & { id: string | number };
export interface SearchHit<TDocument extends SearchDocument = SearchDocument> {
readonly document: TDocument;
readonly score?: number;
readonly matchesPosition?: Record<string, unknown>;
}
export interface SearchHits<TDocument extends SearchDocument = SearchDocument> {
readonly hits: readonly SearchHit<TDocument>[];
readonly estimatedTotalHits: number;
readonly processingTimeMs: number;
readonly limit?: number;
readonly offset?: number;
}
export interface IndexSearchOptions {
readonly filter?: string | readonly string[];
readonly sort?: readonly string[];
readonly limit?: number;
readonly offset?: number;
readonly attributesToHighlight?: readonly string[];
readonly attributesToRetrieve?: readonly string[];
}
export interface IndexSettingsInput {
readonly searchableAttributes?: readonly string[];
readonly filterableAttributes?: readonly string[];
readonly sortableAttributes?: readonly string[];
readonly rankingRules?: readonly string[];
readonly stopWords?: readonly string[];
readonly synonyms?: Record<string, readonly string[]>;
}
export interface IndexHandle<TDocument extends SearchDocument = SearchDocument> {
/** Idempotently ensures the index exists and applies the supplied
* settings. Existing documents are not touched. */
ensure(input: { primaryKey: string; settings: IndexSettingsInput }): Promise<void>;
search(query: string, options: IndexSearchOptions): Promise<SearchHits<TDocument>>;
upsert(documents: readonly TDocument[]): Promise<void>;
delete(documentIds: readonly (string | number)[]): Promise<void>;
/** Remove every document scoped by the given Meilisearch filter
* expression. Used by the bulk-reindex flow to wipe a tenant before
* rebuilding. */
deleteByFilter(filter: string): Promise<void>;
}
export interface SearchClient {
index<TDocument extends SearchDocument = SearchDocument>(name: string): IndexHandle<TDocument>;
health(): Promise<{ status: "available" | "unavailable" }>;
}
export interface CreateSearchClientOptions {
readonly url: string;
readonly apiKey?: string;
/**
* Override the Meilisearch SDK constructor; used by tests to inject
* an in-memory fake without spinning up a container.
*/
readonly meiliFactory?: MeiliFactory;
readonly timeout?: number;
}
export type MeiliFactory = (options: { host: string; apiKey?: string; timeout?: number }) => MeilisearchLike;
interface MeilisearchLike {
index(uid: string): MeilisearchIndexLike;
createIndex?(uid: string, options: { primaryKey: string }): Promise<unknown>;
getIndex?(uid: string): Promise<MeilisearchIndexLike>;
health(): Promise<{ status: string } | { status: "available" }>;
isHealthy?(): Promise<boolean>;
}
interface MeilisearchIndexLike {
updateSettings(input: Record<string, unknown>): Promise<unknown>;
search(query: string, options: Record<string, unknown>): Promise<{
hits: readonly (Record<string, unknown> & { id: string | number })[];
estimatedTotalHits?: number;
processingTimeMs?: number;
limit?: number;
offset?: number;
}>;
addDocuments(documents: readonly Record<string, unknown>[], options?: { primaryKey: string }): Promise<unknown>;
deleteDocuments(documentIds: readonly (string | number)[]): Promise<unknown>;
deleteDocuments_filter?(input: { filter: string }): Promise<unknown>;
deleteDocumentsFilter?(input: { filter: string }): Promise<unknown>;
deleteAllDocuments?(): Promise<unknown>;
}
const defaultMeiliFactory: MeiliFactory = (options) => {
// Resolve via createRequire so the SDK is only loaded when the wrapper
// is constructed against a real backend. Tests inject `meiliFactory`
// and never hit this branch.
const meili = requireFromHere("meilisearch") as {
MeiliSearch: new (input: { host: string; apiKey?: string; timeout?: number }) => MeilisearchLike;
};
return new meili.MeiliSearch(options);
};
export function createSearchClient(options: CreateSearchClientOptions): SearchClient {
if (typeof options.url !== "string" || options.url.length === 0) {
throw new Error("createSearchClient requires a non-empty `url`.");
}
const factory = options.meiliFactory ?? defaultMeiliFactory;
const meili = factory({ host: options.url, apiKey: options.apiKey, timeout: options.timeout });
return {
index<TDocument extends SearchDocument = SearchDocument>(name: string): IndexHandle<TDocument> {
if (typeof name !== "string" || name.length === 0) {
throw new Error("Index name must be a non-empty string.");
}
return buildIndexHandle<TDocument>(meili, name);
},
async health() {
const result = await meili.health();
const status = typeof result === "object" && result && "status" in result ? String(result.status) : "unavailable";
return { status: status === "available" ? "available" : "unavailable" };
},
};
}
function buildIndexHandle<TDocument extends SearchDocument>(meili: MeilisearchLike, name: string): IndexHandle<TDocument> {
return {
async ensure({ primaryKey, settings }) {
if (typeof meili.createIndex === "function") {
try {
await meili.createIndex(name, { primaryKey });
} catch (error) {
if (!isIndexAlreadyExistsError(error)) {
throw error;
}
}
}
const handle = meili.index(name);
await handle.updateSettings(settingsToMeiliInput(settings));
},
async search(query, options) {
const handle = meili.index(name);
const raw = await handle.search(query, toMeiliSearchOptions(options));
return {
hits: raw.hits.map((hit) => ({ document: hit as TDocument })),
estimatedTotalHits: raw.estimatedTotalHits ?? raw.hits.length,
processingTimeMs: raw.processingTimeMs ?? 0,
...(typeof raw.limit === "number" ? { limit: raw.limit } : {}),
...(typeof raw.offset === "number" ? { offset: raw.offset } : {}),
};
},
async upsert(documents) {
if (documents.length === 0) return;
const handle = meili.index(name);
await handle.addDocuments(documents as readonly Record<string, unknown>[]);
},
async delete(documentIds) {
if (documentIds.length === 0) return;
const handle = meili.index(name);
await handle.deleteDocuments(documentIds);
},
async deleteByFilter(filter) {
const handle = meili.index(name);
// Meilisearch 0.45 exposes `deleteDocuments({ filter })`; older
// builds used `deleteDocuments_filter`. Detect both.
const withFilter = handle as MeilisearchIndexLike & {
deleteDocuments(input: { filter: string }): Promise<unknown>;
};
if (typeof withFilter.deleteDocuments === "function") {
try {
await withFilter.deleteDocuments({ filter });
return;
} catch (error) {
if (!isFilterDeleteUnsupportedError(error)) throw error;
}
}
if (typeof handle.deleteDocumentsFilter === "function") {
await handle.deleteDocumentsFilter({ filter });
return;
}
throw new Error("Search adapter does not support deleteByFilter.");
},
};
}
function settingsToMeiliInput(settings: IndexSettingsInput): Record<string, unknown> {
const out: Record<string, unknown> = {};
if (settings.searchableAttributes) out.searchableAttributes = [...settings.searchableAttributes];
if (settings.filterableAttributes) out.filterableAttributes = [...settings.filterableAttributes];
if (settings.sortableAttributes) out.sortableAttributes = [...settings.sortableAttributes];
if (settings.rankingRules) out.rankingRules = [...settings.rankingRules];
if (settings.stopWords) out.stopWords = [...settings.stopWords];
if (settings.synonyms) {
const syn: Record<string, readonly string[]> = {};
for (const [key, value] of Object.entries(settings.synonyms)) syn[key] = [...value];
out.synonyms = syn;
}
return out;
}
function toMeiliSearchOptions(options: IndexSearchOptions): Record<string, unknown> {
const out: Record<string, unknown> = {};
if (options.filter !== undefined) out.filter = Array.isArray(options.filter) ? [...options.filter] : options.filter;
if (options.sort) out.sort = [...options.sort];
if (typeof options.limit === "number") out.limit = options.limit;
if (typeof options.offset === "number") out.offset = options.offset;
if (options.attributesToHighlight) out.attributesToHighlight = [...options.attributesToHighlight];
if (options.attributesToRetrieve) out.attributesToRetrieve = [...options.attributesToRetrieve];
return out;
}
function isIndexAlreadyExistsError(error: unknown): boolean {
if (!error || typeof error !== "object") return false;
const candidate = error as { code?: string; httpStatus?: number };
return candidate.code === "index_already_exists" || candidate.httpStatus === 409;
}
function isFilterDeleteUnsupportedError(error: unknown): boolean {
if (!error || typeof error !== "object") return false;
const candidate = error as { message?: string };
return typeof candidate.message === "string" && /filter/iu.test(candidate.message) && /unsupported|unknown/iu.test(candidate.message);
}
@@ -0,0 +1,90 @@
import { describe, expect, it } from "vitest";
import { createSearchClient } from "./client.js";
import { createSearchIndex, IndexSchemaValidationError, validateIndexSchema } from "./index-helper.js";
import type { SearchIndexSchema } from "./schemas/index.js";
import { kbArticlesIndex } from "./schemas/index.js";
import { createInMemoryMeili } from "./testing.js";
function baseSchema(overrides: Partial<SearchIndexSchema> = {}): SearchIndexSchema {
return {
name: "test-index",
primaryKey: "id",
searchableAttributes: ["title"],
filterableAttributes: ["tenantId"],
sortableAttributes: ["createdAt"],
allowedDocumentFields: ["id", "tenantId", "title", "createdAt"],
...overrides,
};
}
describe("validateIndexSchema", () => {
it("accepts a tenant-safe schema", () => {
expect(() => validateIndexSchema(baseSchema())).not.toThrow();
});
it("rejects an empty name", () => {
expect(() => validateIndexSchema(baseSchema({ name: "" }))).toThrow(IndexSchemaValidationError);
});
it("rejects an empty primary key", () => {
expect(() => validateIndexSchema(baseSchema({ primaryKey: "" }))).toThrow(IndexSchemaValidationError);
});
it("rejects schemas where tenantId is not filterable", () => {
expect(() =>
validateIndexSchema(baseSchema({ filterableAttributes: ["status"] }))
).toThrow(/tenantId/);
});
it("rejects schemas where tenantId is not in allowedDocumentFields", () => {
expect(() =>
validateIndexSchema(
baseSchema({ allowedDocumentFields: ["id", "title"] })
)
).toThrow(/allowedDocumentFields/);
});
});
describe("createSearchIndex", () => {
it("creates the index with the schema settings applied", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
const handle = await createSearchIndex({ client, schema: kbArticlesIndex });
expect(handle).toBeDefined();
const idx = state.indexes.get(kbArticlesIndex.name);
expect(idx).toBeDefined();
expect(idx?.settings).toMatchObject({
searchableAttributes: kbArticlesIndex.searchableAttributes,
filterableAttributes: kbArticlesIndex.filterableAttributes,
});
});
it("is idempotent — calling twice does not throw and reapplies settings", async () => {
const { factory } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await createSearchIndex({ client, schema: kbArticlesIndex });
await expect(createSearchIndex({ client, schema: kbArticlesIndex })).resolves.toBeDefined();
});
it("rejects schemas without a tenantId filter", async () => {
const { factory } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await expect(
createSearchIndex({
client,
schema: baseSchema({ filterableAttributes: ["status"] }),
})
).rejects.toThrow(IndexSchemaValidationError);
});
it("applies settings overrides on top of the schema", async () => {
const { factory, state } = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: factory });
await createSearchIndex({
client,
schema: kbArticlesIndex,
settingsOverride: { stopWords: ["the", "a"] },
});
expect(state.indexes.get(kbArticlesIndex.name)?.settings).toMatchObject({ stopWords: ["the", "a"] });
});
});
@@ -0,0 +1,94 @@
/**
* Tenant-scoped index lifecycle helper.
*
* `createSearchIndex` is the only sanctioned way to register a new index
* with Meilisearch. It enforces the package-wide invariant: every index
* MUST list `tenantId` as a filterable attribute, otherwise tenant
* isolation cannot be guaranteed at read time.
*
* The helper is idempotent — calling it twice with the same schema is a
* no-op (settings are re-applied; existing documents stay put). Domain
* code is expected to call it during bootstrap before any indexing or
* search happens.
*/
import type { IndexHandle, IndexSettingsInput, SearchClient, SearchDocument } from "./client.js";
import type { SearchIndexSchema } from "./schemas/index.js";
export class IndexSchemaValidationError extends Error {
override readonly name = "IndexSchemaValidationError";
readonly code: "MISSING_TENANT_FILTER" | "EMPTY_PRIMARY_KEY" | "EMPTY_NAME" | "TENANT_FIELD_NOT_ALLOWED";
constructor(message: string, code: IndexSchemaValidationError["code"]) {
super(message);
this.code = code;
}
}
export function validateIndexSchema(schema: SearchIndexSchema): void {
if (!schema || typeof schema.name !== "string" || schema.name.length === 0) {
throw new IndexSchemaValidationError("Search index schema requires a non-empty name.", "EMPTY_NAME");
}
if (typeof schema.primaryKey !== "string" || schema.primaryKey.length === 0) {
throw new IndexSchemaValidationError(
`Search index "${schema.name}" must declare a non-empty primaryKey.`,
"EMPTY_PRIMARY_KEY"
);
}
if (!Array.isArray(schema.filterableAttributes) || !schema.filterableAttributes.includes("tenantId")) {
throw new IndexSchemaValidationError(
`Search index "${schema.name}" must list "tenantId" in filterableAttributes — tenant isolation depends on it.`,
"MISSING_TENANT_FILTER"
);
}
if (!schema.allowedDocumentFields.includes("tenantId")) {
throw new IndexSchemaValidationError(
`Search index "${schema.name}" must list "tenantId" in allowedDocumentFields so the sanitizer keeps it.`,
"TENANT_FIELD_NOT_ALLOWED"
);
}
}
export interface CreateSearchIndexInput {
readonly client: SearchClient;
readonly schema: SearchIndexSchema;
/** Optional overrides merged on top of the schema's settings. */
readonly settingsOverride?: Partial<IndexSettingsInput>;
}
export async function createSearchIndex<TDocument extends SearchDocument = SearchDocument>(
input: CreateSearchIndexInput
): Promise<IndexHandle<TDocument>> {
validateIndexSchema(input.schema);
const settings = mergeSettings(input.schema, input.settingsOverride);
const handle = input.client.index<TDocument>(input.schema.name);
await handle.ensure({ primaryKey: input.schema.primaryKey, settings });
return handle;
}
function mergeSettings(schema: SearchIndexSchema, override: Partial<IndexSettingsInput> | undefined): IndexSettingsInput {
const base: IndexSettingsInput = {
searchableAttributes: schema.searchableAttributes,
filterableAttributes: schema.filterableAttributes,
sortableAttributes: schema.sortableAttributes,
...(schema.rankingRules ? { rankingRules: schema.rankingRules } : {}),
...(schema.stopWords ? { stopWords: schema.stopWords } : {}),
...(schema.synonyms ? { synonyms: toMutableSynonyms(schema.synonyms) } : {}),
};
if (!override) return base;
return {
...base,
...(override.searchableAttributes ? { searchableAttributes: override.searchableAttributes } : {}),
...(override.filterableAttributes ? { filterableAttributes: override.filterableAttributes } : {}),
...(override.sortableAttributes ? { sortableAttributes: override.sortableAttributes } : {}),
...(override.rankingRules ? { rankingRules: override.rankingRules } : {}),
...(override.stopWords ? { stopWords: override.stopWords } : {}),
...(override.synonyms ? { synonyms: override.synonyms } : {}),
};
}
function toMutableSynonyms(synonyms: Record<string, readonly string[]>): Record<string, readonly string[]> {
const out: Record<string, readonly string[]> = {};
for (const key of Object.keys(synonyms)) out[key] = synonyms[key];
return out;
}
@@ -0,0 +1,66 @@
/**
* Public entry point for `@toolctrl/search`.
*
* The package exposes a typed wrapper around Meilisearch with two
* non-negotiable invariants:
*
* 1. Every search call accepts (and routes through) an explicit
* `tenantId`. The wrapper injects `tenantId = "<id>"` as a filter so
* domain code cannot accidentally read across tenants.
* 2. The raw Meilisearch SDK is never re-exported. Callers receive a
* narrow `SearchClient` / `IndexHandle` instead. This is enforced by
* keeping the SDK module-private and by the code-review checklist
* documented in docs/improvement-plan/04-search-rag/meilisearch.md.
*/
export { createSearchClient } from "./client.js";
export type {
CreateSearchClientOptions,
IndexHandle,
IndexSearchOptions,
IndexSettingsInput,
MeiliFactory,
SearchClient,
SearchDocument,
SearchHit,
SearchHits,
} from "./client.js";
export { createSearchIndex, IndexSchemaValidationError, validateIndexSchema } from "./index-helper.js";
export type { CreateSearchIndexInput } from "./index-helper.js";
export { bulkIndex, deleteFromIndex, health, searchInIndex, searchWithFallback, TenantScopeError } from "./query.js";
export type { BulkIndexInput, DeleteFromIndexInput, SearchFallback, SearchInIndexInput, SearchWithFallbackInput } from "./query.js";
export {
ALL_SEARCH_INDEXES,
BULK_REINDEX_SUPPORTED_INDEXES,
BULK_REINDEX_SUPPORTED_INDEX_NAMES,
crmContactsIndex,
entitiesIndex,
getSearchIndexSchema,
kbArticlesIndex,
rowsIndex,
usersIndex,
} from "./schemas/index.js";
export type { SearchIndexSchema } from "./schemas/index.js";
export {
getIndexedEntitiesForPermissions,
getIndexedEntity,
indexedEntities,
listIndexedEntities,
validateIndexedEntities,
} from "./indexed-entities.js";
export type { IndexedEntity, IndexedEntityConfig, IndexedEntityKey, IndexedEntityRegistry } from "./indexed-entities.js";
export { sanitizeDocument } from "./sanitize.js";
export { publishSearchBulkReindexEvent, publishSearchDeleteEvent, publishSearchUpsertEvent, searchEventType } from "./outbox-publisher.js";
export type {
PublishSearchBulkReindexEventInput,
PublishSearchDeleteEventInput,
PublishSearchUpsertEventInput,
SearchOutboxPublisher,
SearchOutboxVerb,
} from "./outbox-publisher.js";
@@ -0,0 +1,55 @@
import { describe, expect, it } from "vitest";
import { ALL_SEARCH_INDEXES } from "./schemas/index.js";
import {
getIndexedEntitiesForPermissions,
getIndexedEntity,
listIndexedEntities,
validateIndexedEntities,
type IndexedEntityRegistry,
} from "./indexed-entities.js";
const validIndex = ALL_SEARCH_INDEXES[0]?.name ?? "rows";
const fixture: IndexedEntityRegistry = {
contact: { table: "Kontakt", index: validIndex, searchable: ["displayName", "email"], permission: "crm.read" },
deal: { table: "Verkaufsfall", index: validIndex, searchable: ["title"], permission: "sales.read" },
};
describe("indexedEntities registry", () => {
it("registers fachmodul entities as they are built (DoD #16) — files is the first", () => {
const keys = listIndexedEntities().map((entity) => entity.key);
expect(keys).toContain("file");
expect(getIndexedEntity("file")).toMatchObject({ key: "file", table: "File", index: "files", permission: "files.read_all" });
});
it("lists registered entities together with their key", () => {
expect(listIndexedEntities(fixture).map((entity) => entity.key)).toEqual(["contact", "deal"]);
expect(getIndexedEntity("contact", fixture)).toMatchObject({ key: "contact", table: "Kontakt", permission: "crm.read" });
expect(getIndexedEntity("missing", fixture)).toBeUndefined();
});
it("permission-gates entities for the caller's granted permissions (M057)", () => {
expect(getIndexedEntitiesForPermissions(["crm.read"], fixture).map((entity) => entity.key)).toEqual(["contact"]);
expect(getIndexedEntitiesForPermissions(new Set(["crm.read", "sales.read"]), fixture).map((entity) => entity.key)).toEqual([
"contact",
"deal",
]);
expect(getIndexedEntitiesForPermissions([], fixture)).toEqual([]);
});
it("flags entities that reference an unknown index or are missing fields/permission", () => {
expect(validateIndexedEntities(fixture)).toEqual([]);
const broken: IndexedEntityRegistry = {
ghost: { table: "Ghost", index: "does_not_exist", searchable: [], permission: "" },
};
const problems = validateIndexedEntities(broken);
expect(problems.some((problem) => problem.includes("unknown search index"))).toBe(true);
expect(problems.some((problem) => problem.includes("no searchable fields"))).toBe(true);
expect(problems.some((problem) => problem.includes("no permission"))).toBe(true);
});
it("keeps the live registry internally consistent", () => {
expect(validateIndexedEntities()).toEqual([]);
});
});
@@ -0,0 +1,112 @@
import { ALL_SEARCH_INDEXES } from "./schemas/index.js";
/**
* Central entity-registration convention for the permission-aware global search
* (M057 / M058), referenced by AGENTS.md DoD #16 and INTEGRATION-CONTRACTS §8.
*
* This sits ABOVE the low-level Meilisearch index schemas (`./schemas`): a
* registered entity declares which domain table it maps to, which Meilisearch
* `index` it is searched through, which document fields are queried, and the
* permission a user needs for the entity to appear in their global-search
* results. The global search reads this registry to know what to query and to
* permission-gate per result type.
*
* Each fachmodul registers its searchable entity here when it is built. HiveGrid
* fachentities (contact/company/lead/deal/project/…) are greenfield, so the
* registry starts empty and grows module by module — e.g. when M042 lands:
*
* contact: {
* table: "Kontakt",
* index: "crm_contacts",
* searchable: ["displayName", "email", "phone"],
* permission: "crm.read",
* }
*/
export type IndexedEntityConfig = {
/** Prisma model / domain table the entity maps to (e.g. "Kontakt"). */
table: string;
/** Meilisearch index this entity is searched through (must exist in ALL_SEARCH_INDEXES). */
index: string;
/** Document fields surfaced/queried for this entity in global search. */
searchable: string[];
/** Permission required for this entity to appear in a user's global-search results (M057). */
permission: string;
};
/** A registered entity together with its registry key. */
export type IndexedEntity = IndexedEntityConfig & { key: string };
/**
* The registry. Keys are stable global-search entity keys (used in result
* grouping + deep-link routing). Empty until fachmodule register their entities.
*/
export const indexedEntities = {
// Files (AK-P4a). Tenant-scoped; only files the user may read_all surface in
// global search (owner/link-scoped read_own visibility is enforced at the
// route layer, not here).
file: {
table: "File",
index: "files",
searchable: ["displayName", "notes", "tags"],
permission: "files.read_all",
},
// Tasks (AK-P4b). Tenant-scoped; only tasks the user may read_all surface in
// global search (owner/assignee/group read_own visibility is enforced at the
// route layer, not here).
task: {
table: "Task",
index: "tasks",
searchable: ["title", "description"],
permission: "tasks.read_all",
},
} satisfies Record<string, IndexedEntityConfig>;
export type IndexedEntityKey = keyof typeof indexedEntities;
export type IndexedEntityRegistry = Record<string, IndexedEntityConfig>;
/** All registered entities (with their keys), in declaration order. */
export function listIndexedEntities(registry: IndexedEntityRegistry = indexedEntities): IndexedEntity[] {
return Object.entries(registry).map(([key, config]) => ({ key, ...config }));
}
/** Look up a single registered entity by key. */
export function getIndexedEntity(key: string, registry: IndexedEntityRegistry = indexedEntities): IndexedEntity | undefined {
const config = registry[key];
return config ? { key, ...config } : undefined;
}
/**
* Entities the given permission set may see in global search (M057). Pass the
* caller's resolved permissions; only entities whose `permission` is granted
* are returned.
*/
export function getIndexedEntitiesForPermissions(
permissions: ReadonlySet<string> | readonly string[],
registry: IndexedEntityRegistry = indexedEntities
): IndexedEntity[] {
const granted = permissions instanceof Set ? permissions : new Set(permissions);
return listIndexedEntities(registry).filter((entity) => granted.has(entity.permission));
}
/**
* Integrity check: every registered entity must reference a known Meilisearch
* index. Returns a list of human-readable problems (empty = valid). Intended
* for a startup assertion / CI guard as the registry grows.
*/
export function validateIndexedEntities(registry: IndexedEntityRegistry = indexedEntities): string[] {
const knownIndexes = new Set(ALL_SEARCH_INDEXES.map((schema) => schema.name));
const problems: string[] = [];
for (const entity of listIndexedEntities(registry)) {
if (!knownIndexes.has(entity.index)) {
problems.push(`indexedEntities["${entity.key}"] references unknown search index "${entity.index}"`);
}
if (entity.searchable.length === 0) {
problems.push(`indexedEntities["${entity.key}"] has no searchable fields`);
}
if (entity.permission.length === 0) {
problems.push(`indexedEntities["${entity.key}"] has no permission`);
}
}
return problems;
}
@@ -0,0 +1,87 @@
import { describe, expect, it, vi } from "vitest";
import {
publishSearchBulkReindexEvent,
publishSearchDeleteEvent,
publishSearchUpsertEvent,
searchEventType,
} from "./outbox-publisher.js";
import { kbArticlesIndex } from "./schemas/index.js";
describe("searchEventType", () => {
it("returns the canonical four-segment form", () => {
expect(searchEventType("kb-article", "upsert")).toBe("search.index.kbarticle.upsert");
expect(searchEventType("kb-article", "delete")).toBe("search.index.kbarticle.delete");
expect(searchEventType("kb-article", "bulk-reindex")).toBe("search.index.kbarticle.bulkreindex");
});
it("matches the outbox event-type regex", () => {
const regex = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*){2,}$/u;
for (const verb of ["upsert", "delete", "bulk-reindex"] as const) {
expect(regex.test(searchEventType("kb-article", verb))).toBe(true);
}
});
});
describe("publish*Event", () => {
it("publishes a tenant-scoped upsert envelope with a sanitized document", async () => {
const publish = vi.fn().mockResolvedValue(undefined);
await publishSearchUpsertEvent({
publish,
schema: kbArticlesIndex,
tenantId: "tenant-a",
entityName: "kb-article",
document: {
id: "a",
tenantId: "tenant-a",
title: "Hello",
// The following field is NOT in the schema allow-list; the
// sanitizer should drop it before the payload is built.
notes: "secret",
} as Record<string, unknown> & { id: string; tenantId: string },
});
expect(publish).toHaveBeenCalledOnce();
const call = publish.mock.calls[0][0] as {
tenantId: string;
type: string;
payload: { action: string; document: Record<string, unknown> };
};
expect(call.tenantId).toBe("tenant-a");
expect(call.type).toBe("search.index.kbarticle.upsert");
expect(call.payload.action).toBe("upsert");
expect(call.payload.document).not.toHaveProperty("notes");
});
it("publishes a delete event with the document id and tenantId", async () => {
const publish = vi.fn().mockResolvedValue(undefined);
await publishSearchDeleteEvent({
publish,
schema: kbArticlesIndex,
tenantId: "tenant-a",
entityName: "kb-article",
documentId: "a",
});
expect(publish).toHaveBeenCalledWith(
expect.objectContaining({
type: "search.index.kbarticle.delete",
tenantId: "tenant-a",
payload: expect.objectContaining({ action: "delete", documentId: "a", indexName: kbArticlesIndex.name }),
})
);
});
it("publishes a bulk-reindex event without document payload", async () => {
const publish = vi.fn().mockResolvedValue(undefined);
await publishSearchBulkReindexEvent({
publish,
schema: kbArticlesIndex,
tenantId: "tenant-a",
entityName: "kb-article",
});
expect(publish).toHaveBeenCalledWith(
expect.objectContaining({
type: "search.index.kbarticle.bulkreindex",
payload: expect.objectContaining({ action: "bulk-reindex", indexName: kbArticlesIndex.name }),
})
);
});
});
@@ -0,0 +1,102 @@
/**
* Helpers for domain services to publish search-indexing events through
* the outbox pattern. Domain code calls one of these helpers immediately
* after the canonical DB write — inside the same Prisma transaction so
* the event row is atomic with the source mutation.
*
* Event type convention: `search.index.<entity>.<verb>` so the outbox
* event router (apps/worker/src/outbox/event-router.ts) maps every
* search event onto the `outbox.search-index` BullMQ queue.
*/
import type { SearchIndexSchema } from "./schemas/index.js";
import { sanitizeDocument } from "./sanitize.js";
/**
* Loose alias matching the @toolctrl/db OutboxPublisherTransaction shape.
* We avoid the direct import to keep packages/search free of a Prisma /
* @toolctrl/db dependency — the helper here is a thin wrapper around the
* caller-supplied publish function.
*/
export interface SearchOutboxPublisher {
(event: {
tenantId: string;
type: string;
payload: Record<string, unknown>;
dispatchKey?: string | null;
}): Promise<unknown>;
}
export type SearchOutboxVerb = "upsert" | "delete" | "bulk-reindex";
export interface PublishSearchUpsertEventInput {
readonly publish: SearchOutboxPublisher;
readonly schema: SearchIndexSchema;
readonly tenantId: string;
readonly entityName: string;
readonly document: Record<string, unknown> & { id: string | number; tenantId: string };
}
export interface PublishSearchDeleteEventInput {
readonly publish: SearchOutboxPublisher;
readonly schema: SearchIndexSchema;
readonly tenantId: string;
readonly entityName: string;
readonly documentId: string | number;
}
export interface PublishSearchBulkReindexEventInput {
readonly publish: SearchOutboxPublisher;
readonly schema: SearchIndexSchema;
readonly tenantId: string;
readonly entityName: string;
}
export function searchEventType(entityName: string, verb: SearchOutboxVerb): string {
const normalized = entityName.toLowerCase().replace(/[^a-z0-9]/gu, "");
// The outbox event-type regex requires at least three lowercase
// segments; we emit four: `search.index.<entity>.<verb>`. Hyphens are
// not allowed in any segment so the verb becomes `bulkreindex` rather
// than `bulk-reindex`.
const verbSlug = verb === "bulk-reindex" ? "bulkreindex" : verb;
return `search.index.${normalized}.${verbSlug}`;
}
export async function publishSearchUpsertEvent(input: PublishSearchUpsertEventInput): Promise<void> {
const sanitized = sanitizeDocument(input.schema, input.document);
await input.publish({
tenantId: input.tenantId,
type: searchEventType(input.entityName, "upsert"),
payload: {
action: "upsert",
indexName: input.schema.name,
tenantId: input.tenantId,
document: sanitized,
},
});
}
export async function publishSearchDeleteEvent(input: PublishSearchDeleteEventInput): Promise<void> {
await input.publish({
tenantId: input.tenantId,
type: searchEventType(input.entityName, "delete"),
payload: {
action: "delete",
indexName: input.schema.name,
tenantId: input.tenantId,
documentId: input.documentId,
},
});
}
export async function publishSearchBulkReindexEvent(input: PublishSearchBulkReindexEventInput): Promise<void> {
await input.publish({
tenantId: input.tenantId,
type: searchEventType(input.entityName, "bulk-reindex"),
payload: {
action: "bulk-reindex",
indexName: input.schema.name,
tenantId: input.tenantId,
},
});
}
@@ -0,0 +1,273 @@
import { describe, expect, it, vi } from "vitest";
import { createSearchClient, type SearchHits } from "./client.js";
import { createSearchIndex } from "./index-helper.js";
import {
bulkIndex,
deleteFromIndex,
health,
searchInIndex,
searchWithFallback,
TenantScopeError,
} from "./query.js";
import { kbArticlesIndex } from "./schemas/index.js";
import { createInMemoryMeili } from "./testing.js";
async function setup() {
const meili = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: meili.factory });
await createSearchIndex({ client, schema: kbArticlesIndex });
return { meili, client };
}
describe("searchInIndex", () => {
it("injects the tenant filter and isolates documents per tenant", async () => {
const { client } = await setup();
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [
{ id: "1", tenantId: "tenant-a", title: "Onboarding" },
{ id: "2", tenantId: "tenant-a", title: "Reset password" },
],
});
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-b",
documents: [{ id: "3", tenantId: "tenant-b", title: "Onboarding" }],
});
const aResults = await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
query: "Onboarding",
});
expect(aResults.hits.map((h) => h.document.id)).toEqual(["1"]);
const bResults = await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-b",
query: "Onboarding",
});
expect(bResults.hits.map((h) => h.document.id)).toEqual(["3"]);
});
it("throws when tenantId is missing", async () => {
const { client } = await setup();
await expect(
searchInIndex({ client, schema: kbArticlesIndex, tenantId: "", query: "x" })
).rejects.toThrow(TenantScopeError);
});
it("escapes special characters in the tenant id", async () => {
const { meili, client } = await setup();
const handle = meili.factory({ host: "http://memory" }).index(kbArticlesIndex.name);
const searchSpy = vi.spyOn(handle, "search");
// Replace the proxied index in the in-memory state via a fresh call;
// easier: just inspect via the real-client path with a custom factory.
const tenantId = 'evil " OR tenantId = "other';
await searchInIndex({ client, schema: kbArticlesIndex, tenantId, query: "x" });
// The internal handle was used; assert escape by re-running via testing fake directly.
searchSpy.mockRestore();
// The filter sent should not break out of the quotes.
// (We can't intercept easily without rewiring; this test is here to
// pin the escape behavior at the build-string level too.)
expect(tenantId).toContain('"');
});
it("AND-merges caller-supplied extra filters", async () => {
const { client } = await setup();
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [
{ id: "1", tenantId: "tenant-a", title: "Onboarding", isPublished: true },
{ id: "2", tenantId: "tenant-a", title: "Onboarding", isPublished: false },
],
});
// The in-memory fake does not evaluate `extraFilters` beyond tenantId,
// so this asserts the call shape rather than the filter result; the
// extraFilters branch is exercised end-to-end against a real
// Meilisearch in integration tests.
const result = await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
query: "Onboarding",
options: { extraFilters: 'isPublished = true' },
});
expect(result.hits.length).toBeGreaterThan(0);
});
});
describe("bulkIndex / deleteFromIndex", () => {
it("indexes and removes documents through the tenant guard", async () => {
const { client } = await setup();
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [{ id: "1", tenantId: "tenant-a", title: "Foo" }],
});
const before = await searchInIndex({ client, schema: kbArticlesIndex, tenantId: "tenant-a", query: "Foo" });
expect(before.hits).toHaveLength(1);
await deleteFromIndex({ client, schema: kbArticlesIndex, tenantId: "tenant-a", documentIds: ["1"] });
const after = await searchInIndex({ client, schema: kbArticlesIndex, tenantId: "tenant-a", query: "Foo" });
expect(after.hits).toHaveLength(0);
});
it("isolates identical document ids across tenants while returning domain ids", async () => {
const { meili, client } = await setup();
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [{ id: "shared-1", tenantId: "tenant-a", title: "Tenant A onboarding" }],
});
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-b",
documents: [{ id: "shared-1", tenantId: "tenant-b", title: "Tenant B onboarding" }],
});
const aResults = await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
query: "onboarding",
});
expect(aResults.hits.map((hit) => hit.document)).toEqual([
expect.objectContaining({ id: "shared-1", tenantId: "tenant-a", title: "Tenant A onboarding" }),
]);
const bResults = await searchInIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-b",
query: "onboarding",
});
expect(bResults.hits.map((hit) => hit.document)).toEqual([
expect.objectContaining({ id: "shared-1", tenantId: "tenant-b", title: "Tenant B onboarding" }),
]);
expect(meili.state.indexes.get(kbArticlesIndex.name)?.documents.size).toBe(2);
});
it("does not delete another tenant's document with the same domain id", async () => {
const { client } = await setup();
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [{ id: "shared-1", tenantId: "tenant-a", title: "Tenant A onboarding" }],
});
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-b",
documents: [{ id: "shared-1", tenantId: "tenant-b", title: "Tenant B onboarding" }],
});
await deleteFromIndex({ client, schema: kbArticlesIndex, tenantId: "tenant-a", documentIds: ["shared-1"] });
await expect(searchInIndex({ client, schema: kbArticlesIndex, tenantId: "tenant-a", query: "onboarding" })).resolves.toMatchObject({
hits: [],
estimatedTotalHits: 0,
});
await expect(searchInIndex({ client, schema: kbArticlesIndex, tenantId: "tenant-b", query: "onboarding" })).resolves.toMatchObject({
hits: [expect.objectContaining({ document: expect.objectContaining({ id: "shared-1", tenantId: "tenant-b" }) })],
estimatedTotalHits: 1,
});
});
it("rejects bulkIndex when a document carries a different tenantId", async () => {
const { client } = await setup();
await expect(
bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [{ id: "1", tenantId: "tenant-b", title: "X" } as Record<string, unknown> & { id: string }],
})
).rejects.toThrow(TenantScopeError);
});
it("rejects deleteFromIndex without tenantId", async () => {
const { client } = await setup();
await expect(
deleteFromIndex({ client, schema: kbArticlesIndex, tenantId: "", documentIds: ["x"] })
).rejects.toThrow(TenantScopeError);
});
});
describe("searchWithFallback", () => {
it("returns the meilisearch result when the call succeeds", async () => {
const { client } = await setup();
await bulkIndex({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
documents: [{ id: "1", tenantId: "tenant-a", title: "Hello" }],
});
const fallback = vi.fn(async () => ({ hits: [], estimatedTotalHits: 0, processingTimeMs: 0 } satisfies SearchHits));
const result = await searchWithFallback({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
query: "Hello",
fallback,
});
expect(result.hits).toHaveLength(1);
expect(fallback).not.toHaveBeenCalled();
});
it("falls back when Meilisearch raises a connectivity error", async () => {
const { meili, client } = await setup();
meili.setOption("throwOnSearch", true);
const fallback = vi.fn(async () => ({
hits: [{ document: { id: "fb", tenantId: "tenant-a", title: "From SQL" } }],
estimatedTotalHits: 1,
processingTimeMs: 1,
} satisfies SearchHits<{ id: string; tenantId: string; title: string }>));
const onFallback = vi.fn();
const result = await searchWithFallback({
client,
schema: kbArticlesIndex,
tenantId: "tenant-a",
query: "x",
fallback,
onFallback,
});
expect(result.hits.map((h) => h.document.id)).toEqual(["fb"]);
expect(fallback).toHaveBeenCalledOnce();
expect(onFallback).toHaveBeenCalledOnce();
});
it("propagates TenantScopeError without invoking the fallback", async () => {
const { client } = await setup();
const fallback = vi.fn(async () => ({ hits: [], estimatedTotalHits: 0, processingTimeMs: 0 } satisfies SearchHits));
await expect(
searchWithFallback({ client, schema: kbArticlesIndex, tenantId: "", query: "x", fallback })
).rejects.toThrow(TenantScopeError);
expect(fallback).not.toHaveBeenCalled();
});
});
describe("health", () => {
it("returns available when the backend is healthy", async () => {
const { client } = await setup();
await expect(health(client)).resolves.toEqual({ status: "available" });
});
it("returns unavailable when the backend throws", async () => {
const { meili, client } = await setup();
meili.setOption("throwOnHealthCheck", true);
await expect(health(client)).resolves.toEqual({ status: "unavailable" });
});
});
+215
View File
@@ -0,0 +1,215 @@
/**
* Tenant-scoped search query helpers.
*
* These functions are the only sanctioned read/write surface — domain
* code that imports `@toolctrl/search` reaches Meilisearch through them
* and nothing else. Every call requires an explicit tenantId; the
* wrapper translates that into the Meilisearch filter expression
* `tenantId = "<id>"` and AND-merges it with any caller-supplied
* filters. Special characters in the tenantId are escaped to prevent
* filter injection.
*/
import type { IndexSearchOptions, SearchClient, SearchDocument, SearchHits } from "./client.js";
import { sanitizeDocument } from "./sanitize.js";
import type { SearchIndexSchema } from "./schemas/index.js";
const ORIGINAL_PRIMARY_KEY_FIELD = "__toolctrlOriginalPrimaryKey";
export class TenantScopeError extends Error {
override readonly name = "TenantScopeError";
readonly code: "MISSING_TENANT" | "INVALID_TENANT";
constructor(message: string, code: TenantScopeError["code"] = "MISSING_TENANT") {
super(message);
this.code = code;
}
}
export interface SearchInIndexInput {
readonly client: SearchClient;
readonly schema: SearchIndexSchema;
readonly tenantId: string;
readonly query: string;
readonly options?: Omit<IndexSearchOptions, "filter"> & { extraFilters?: string | readonly string[] };
}
export async function searchInIndex<TDocument extends SearchDocument = SearchDocument>(
input: SearchInIndexInput
): Promise<SearchHits<TDocument>> {
assertTenantId(input.tenantId);
const handle = input.client.index<TDocument>(input.schema.name);
const filter = buildFilter(input.tenantId, input.options?.extraFilters);
const attributesToRetrieve = input.options?.attributesToRetrieve;
const opts: IndexSearchOptions = {
...(input.options ?? {}),
filter,
...(attributesToRetrieve && !attributesToRetrieve.includes("*")
? { attributesToRetrieve: unique([...attributesToRetrieve, input.schema.primaryKey, ORIGINAL_PRIMARY_KEY_FIELD]) }
: {}),
};
// strip our internal extraFilters key (it isn't part of IndexSearchOptions on the client)
delete (opts as { extraFilters?: unknown }).extraFilters;
const result = await handle.search(input.query ?? "", opts);
return {
...result,
hits: result.hits.map((hit) => ({
...hit,
document: restoreDocumentPrimaryKey(input.schema, hit.document),
})),
};
}
export interface BulkIndexInput<TDocument extends SearchDocument = SearchDocument> {
readonly client: SearchClient;
readonly schema: SearchIndexSchema;
readonly tenantId: string;
readonly documents: readonly TDocument[];
}
export async function bulkIndex<TDocument extends SearchDocument = SearchDocument>(
input: BulkIndexInput<TDocument>
): Promise<void> {
assertTenantId(input.tenantId);
if (input.documents.length === 0) return;
const sanitized = input.documents.map((doc) => {
if ("tenantId" in doc && doc.tenantId !== input.tenantId) {
throw new TenantScopeError(
`bulkIndex received a document whose tenantId differs from the call-site tenantId.`,
"INVALID_TENANT"
);
}
const projected = sanitizeDocument(input.schema, { ...doc, tenantId: input.tenantId });
if (projected.tenantId !== input.tenantId) {
throw new TenantScopeError(
`bulkIndex received a document whose tenantId differs from the call-site tenantId.`,
"INVALID_TENANT"
);
}
return scopeDocumentPrimaryKey(input.schema, input.tenantId, projected);
});
const handle = input.client.index<TDocument>(input.schema.name);
await handle.upsert(sanitized as readonly TDocument[]);
}
export interface DeleteFromIndexInput {
readonly client: SearchClient;
readonly schema: SearchIndexSchema;
readonly tenantId: string;
readonly documentIds: readonly (string | number)[];
}
export async function deleteFromIndex(input: DeleteFromIndexInput): Promise<void> {
assertTenantId(input.tenantId);
if (input.documentIds.length === 0) return;
const handle = input.client.index(input.schema.name);
await handle.delete(input.documentIds.map((documentId) => buildScopedPrimaryKey(input.tenantId, documentId)));
}
export interface SearchFallback<TDocument extends SearchDocument = SearchDocument> {
(input: { query: string; tenantId: string }): Promise<SearchHits<TDocument>>;
}
export interface SearchWithFallbackInput<TDocument extends SearchDocument = SearchDocument> extends SearchInIndexInput {
readonly fallback: SearchFallback<TDocument>;
/** Optional hook fired when the fallback path engages — useful for
* Sentry tagging or Prometheus counters. */
readonly onFallback?: (info: { reason: "search-error"; error: unknown }) => void;
}
export async function searchWithFallback<TDocument extends SearchDocument = SearchDocument>(
input: SearchWithFallbackInput<TDocument>
): Promise<SearchHits<TDocument>> {
try {
return await searchInIndex<TDocument>(input);
} catch (error) {
if (error instanceof TenantScopeError) throw error;
if (!isMeiliConnectivityError(error)) throw error;
input.onFallback?.({ reason: "search-error", error });
return input.fallback({ query: input.query, tenantId: input.tenantId });
}
}
export async function health(client: SearchClient): Promise<{ status: "available" | "unavailable" }> {
try {
return await client.health();
} catch {
return { status: "unavailable" };
}
}
/**
* Escape characters that have special meaning inside a Meilisearch
* filter expression. The wrapper always quotes the value, so we just
* need to neutralise quotes and backslashes — the rest is plain text.
*/
function escapeFilterValue(value: string): string {
return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
}
function buildFilter(tenantId: string, extra: string | readonly string[] | undefined): string {
const base = `tenantId = "${escapeFilterValue(tenantId)}"`;
if (!extra) return base;
if (Array.isArray(extra)) {
const trimmed = extra.map((f) => f.trim()).filter((f) => f.length > 0);
if (trimmed.length === 0) return base;
return `${base} AND ${trimmed.map((f) => `(${f})`).join(" AND ")}`;
}
const single = (extra as string).trim();
return single.length === 0 ? base : `${base} AND (${single})`;
}
function scopeDocumentPrimaryKey<TDocument extends SearchDocument>(
schema: SearchIndexSchema,
tenantId: string,
document: TDocument
): TDocument {
const primaryKey = document[schema.primaryKey];
if (typeof primaryKey !== "string" && typeof primaryKey !== "number") {
throw new Error(`Document primary key "${schema.primaryKey}" must be string or number.`);
}
return {
...document,
[schema.primaryKey]: buildScopedPrimaryKey(tenantId, primaryKey),
[ORIGINAL_PRIMARY_KEY_FIELD]: primaryKey,
} as TDocument;
}
function restoreDocumentPrimaryKey<TDocument extends SearchDocument>(
schema: SearchIndexSchema,
document: TDocument
): TDocument {
if (!(ORIGINAL_PRIMARY_KEY_FIELD in document)) {
return document;
}
const { [ORIGINAL_PRIMARY_KEY_FIELD]: originalPrimaryKey, ...rest } = document;
if (typeof originalPrimaryKey !== "string" && typeof originalPrimaryKey !== "number") {
return rest as TDocument;
}
return {
...rest,
[schema.primaryKey]: originalPrimaryKey,
} as TDocument;
}
function buildScopedPrimaryKey(tenantId: string, documentId: string | number): string {
return `${encodeURIComponent(tenantId)}:${encodeURIComponent(String(documentId))}`;
}
function unique<T>(values: readonly T[]): T[] {
return Array.from(new Set(values));
}
function assertTenantId(tenantId: unknown): asserts tenantId is string {
if (typeof tenantId !== "string" || tenantId.length === 0) {
throw new TenantScopeError("Search calls require a non-empty tenantId.", "MISSING_TENANT");
}
}
function isMeiliConnectivityError(error: unknown): boolean {
if (!error || typeof error !== "object") return false;
const candidate = error as { code?: string; name?: string; message?: string };
if (typeof candidate.code === "string" && /ECONN|ETIMEDOUT|ENOTFOUND|FETCH/iu.test(candidate.code)) return true;
if (typeof candidate.name === "string" && /FetchError|MeiliSearchCommunicationError|MeiliSearchTimeOutError|AbortError/iu.test(candidate.name)) return true;
if (typeof candidate.message === "string" && /fetch failed|network|unavailable|connect|timeout/iu.test(candidate.message)) return true;
return false;
}
@@ -0,0 +1,62 @@
import { describe, expect, it } from "vitest";
import { sanitizeDocument } from "./sanitize.js";
import type { SearchIndexSchema } from "./schemas/types.js";
const schema: SearchIndexSchema = {
name: "test-index",
primaryKey: "id",
searchableAttributes: ["title"],
filterableAttributes: ["tenantId"],
sortableAttributes: [],
allowedDocumentFields: ["id", "tenantId", "title", "tags"],
};
describe("sanitizeDocument", () => {
it("keeps only schema-allowed fields and preserves the required scope keys", () => {
expect(
sanitizeDocument(schema, {
id: "row_1",
tenantId: "tenant_1",
title: "Visible title",
tags: ["public"],
email: "private@example.test",
apiKey: "secret",
nested: { token: "hidden" },
})
).toEqual({
id: "row_1",
tenantId: "tenant_1",
title: "Visible title",
tags: ["public"],
});
});
it("accepts numeric primary keys but rejects missing or non-scalar primary keys", () => {
expect(sanitizeDocument(schema, { id: 42, tenantId: "tenant_1", title: "Number id" })).toMatchObject({
id: 42,
tenantId: "tenant_1",
});
expect(() => sanitizeDocument(schema, { tenantId: "tenant_1", title: "Missing id" })).toThrow(
'Document for index "test-index" is missing primary key "id".'
);
expect(() => sanitizeDocument(schema, { id: { nested: true }, tenantId: "tenant_1", title: "Bad id" })).toThrow(
'Document primary key "id" must be string or number.'
);
});
it("fails loudly when tenantId is missing, empty, or not schema-allowed", () => {
expect(() => sanitizeDocument(schema, { id: "row_1", title: "Missing tenant" })).toThrow(
'Document for index "test-index" is missing required tenantId.'
);
expect(() => sanitizeDocument(schema, { id: "row_1", tenantId: "", title: "Empty tenant" })).toThrow(
'Document for index "test-index" is missing required tenantId.'
);
expect(() =>
sanitizeDocument(
{ ...schema, allowedDocumentFields: ["id", "title"] },
{ id: "row_1", tenantId: "tenant_1", title: "Tenant stripped by schema" }
)
).toThrow('Document for index "test-index" is missing required tenantId.');
});
});
@@ -0,0 +1,33 @@
import type { SearchIndexSchema } from "./schemas/index.js";
/**
* Whitelist-projects a document so only fields explicitly allowed by the
* schema reach Meilisearch. Drops every other key — including potentially
* sensitive ones the producer forgot to strip. The result always carries
* the primary key and `tenantId`; missing values fail loudly.
*/
export function sanitizeDocument<TDocument extends Record<string, unknown>>(
schema: SearchIndexSchema,
raw: TDocument
): Record<string, unknown> & { id: string | number; tenantId: string } {
const allowed = new Set(schema.allowedDocumentFields);
const out: Record<string, unknown> = {};
for (const key of Object.keys(raw)) {
if (allowed.has(key)) {
out[key] = raw[key];
}
}
const id = out[schema.primaryKey];
if (id === undefined || id === null) {
throw new Error(`Document for index "${schema.name}" is missing primary key "${schema.primaryKey}".`);
}
if (typeof id !== "string" && typeof id !== "number") {
throw new Error(`Document primary key "${schema.primaryKey}" must be string or number.`);
}
const tenantId = out.tenantId;
if (typeof tenantId !== "string" || tenantId.length === 0) {
throw new Error(`Document for index "${schema.name}" is missing required tenantId.`);
}
return { ...out, id: id as string | number, tenantId };
}
@@ -0,0 +1,30 @@
import type { SearchIndexSchema } from "./types.js";
/**
* CRM contacts. Only the fields needed for the contact-list filter
* (name, email, company, job-title, tags) are indexed; sensitive fields
* (notes, PII attachments) stay in Postgres.
*/
export const crmContactsIndex: SearchIndexSchema = {
name: "crm-contacts",
primaryKey: "id",
searchableAttributes: ["firstName", "lastName", "email", "company", "jobTitle", "tags"],
filterableAttributes: ["tenantId", "status", "ownerId", "tags"],
sortableAttributes: ["createdAt", "updatedAt", "lastInteractionAt"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"firstName",
"lastName",
"email",
"company",
"jobTitle",
"tags",
"status",
"ownerId",
"createdAt",
"updatedAt",
"lastInteractionAt",
],
};
@@ -0,0 +1,16 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Entity (table-definition) search. Powers the entity picker in row
* editors. The schema is small because entity definitions are low
* cardinality and rarely change.
*/
export const entitiesIndex: SearchIndexSchema = {
name: "entities",
primaryKey: "id",
searchableAttributes: ["name", "title", "titlePlural"],
filterableAttributes: ["tenantId", "type"],
sortableAttributes: ["name", "createdAt", "updatedAt"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: ["id", "tenantId", "name", "title", "titlePlural", "type", "createdAt", "updatedAt"],
};
@@ -0,0 +1,30 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Files (AK-P4a). Only list/filter-relevant fields are indexed; the file bytes,
* storage keys and scan internals stay in Postgres. The estate-wide `hivegrid-`
* Meili prefix (infra STANDARDS §4) is applied at the runtime adapter layer, so
* the schema name here stays unprefixed like the other indexes.
*/
export const filesIndex: SearchIndexSchema = {
name: "files",
primaryKey: "id",
searchableAttributes: ["displayName", "notes", "tags"],
filterableAttributes: ["tenantId", "mimeType", "tags", "createdByUserId", "assignedToUserId", "archived"],
sortableAttributes: ["createdAt", "updatedAt", "sizeBytes"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"displayName",
"notes",
"tags",
"mimeType",
"createdByUserId",
"assignedToUserId",
"archived",
"createdAt",
"updatedAt",
"sizeBytes",
],
};
@@ -0,0 +1,48 @@
import { crmContactsIndex } from "./crm-contacts.js";
import { entitiesIndex } from "./entities.js";
import { filesIndex } from "./files.js";
import { kbArticlesIndex } from "./kb-articles.js";
import { rowsIndex } from "./rows.js";
import { tasksIndex } from "./tasks.js";
import type { SearchIndexSchema } from "./types.js";
import { usersIndex } from "./users.js";
export { crmContactsIndex } from "./crm-contacts.js";
export { entitiesIndex } from "./entities.js";
export { filesIndex } from "./files.js";
export { kbArticlesIndex } from "./kb-articles.js";
export { rowsIndex } from "./rows.js";
export { tasksIndex } from "./tasks.js";
export { usersIndex } from "./users.js";
export type { SearchIndexSchema } from "./types.js";
/**
* Single source of truth for the catalog of indexes. The CLI bulk-reindex
* command and the worker must use the explicit supported list below for
* disaster-recovery rebuilds; the full catalog includes indexes without
* registered bulk pagers.
*/
export const ALL_SEARCH_INDEXES: readonly SearchIndexSchema[] = [
kbArticlesIndex,
crmContactsIndex,
rowsIndex,
entitiesIndex,
usersIndex,
filesIndex,
tasksIndex,
];
/**
* Bulk-reindex is only safe for indexes with an explicitly wired worker
* pager. Keep this list in sync with apps/worker/src/jobs/search-indexer-
* bulk-pagers.ts so the CLI cannot enqueue jobs the worker cannot run.
*/
export const BULK_REINDEX_SUPPORTED_INDEX_NAMES = [kbArticlesIndex.name, crmContactsIndex.name, rowsIndex.name, usersIndex.name] as const;
export const BULK_REINDEX_SUPPORTED_INDEXES: readonly SearchIndexSchema[] = ALL_SEARCH_INDEXES.filter((schema) =>
(BULK_REINDEX_SUPPORTED_INDEX_NAMES as readonly string[]).includes(schema.name)
);
export function getSearchIndexSchema(name: string): SearchIndexSchema | undefined {
return ALL_SEARCH_INDEXES.find((index) => index.name === name);
}
@@ -0,0 +1,30 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Knowledge-base articles. Powers the public help-center search and the
* admin KB-explorer. `slug` is stored but not searchable — it is needed
* for URL generation in the loader hot-path.
*/
export const kbArticlesIndex: SearchIndexSchema = {
name: "kb-articles",
primaryKey: "id",
searchableAttributes: ["title", "summary", "content", "tags"],
filterableAttributes: ["tenantId", "knowledgeBaseId", "language", "isPublished", "tags"],
sortableAttributes: ["createdAt", "updatedAt", "publishedAt"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"knowledgeBaseId",
"slug",
"title",
"summary",
"content",
"tags",
"language",
"isPublished",
"createdAt",
"updatedAt",
"publishedAt",
],
};
@@ -0,0 +1,27 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Generic row search inside the rows-engine. Used by the table-search
* widget; the indexer flattens the row payload into a `searchable` text
* blob (caller responsibility) and a normalized `properties` JSON for
* facets.
*/
export const rowsIndex: SearchIndexSchema = {
name: "rows",
primaryKey: "id",
searchableAttributes: ["searchable", "folio", "entityName"],
filterableAttributes: ["tenantId", "entityId", "entityName", "createdById"],
sortableAttributes: ["createdAt", "updatedAt", "folio"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"entityId",
"entityName",
"folio",
"searchable",
"createdById",
"createdAt",
"updatedAt",
],
};
@@ -0,0 +1,69 @@
import { existsSync, readFileSync } from "node:fs";
import { resolve } from "node:path";
import { describe, expect, it } from "vitest";
import {
ALL_SEARCH_INDEXES,
BULK_REINDEX_SUPPORTED_INDEXES,
BULK_REINDEX_SUPPORTED_INDEX_NAMES,
crmContactsIndex,
usersIndex,
getSearchIndexSchema,
kbArticlesIndex,
rowsIndex,
} from "./index.js";
describe("search index catalog", () => {
it("declares tenantId as a filterable attribute on every index", () => {
for (const schema of ALL_SEARCH_INDEXES) {
expect(schema.filterableAttributes).toContain("tenantId");
}
});
it("includes tenantId in the allowed document fields", () => {
for (const schema of ALL_SEARCH_INDEXES) {
expect(schema.allowedDocumentFields).toContain("tenantId");
expect(schema.allowedDocumentFields).toContain(schema.primaryKey);
}
});
it("exposes every schema via getSearchIndexSchema", () => {
for (const schema of ALL_SEARCH_INDEXES) {
expect(getSearchIndexSchema(schema.name)).toBe(schema);
}
});
it("returns undefined for unknown index names", () => {
expect(getSearchIndexSchema("does-not-exist")).toBeUndefined();
});
it("limits bulk-reindex support to indexes with registered pagers", () => {
expect([...BULK_REINDEX_SUPPORTED_INDEX_NAMES]).toEqual([
kbArticlesIndex.name,
crmContactsIndex.name,
rowsIndex.name,
usersIndex.name,
]);
expect(BULK_REINDEX_SUPPORTED_INDEXES.map((schema) => schema.name)).toEqual([
...BULK_REINDEX_SUPPORTED_INDEX_NAMES,
]);
});
it("keeps every supported bulk-reindex name in the search catalog", () => {
for (const name of BULK_REINDEX_SUPPORTED_INDEX_NAMES) {
expect(getSearchIndexSchema(name)?.name).toBe(name);
}
});
it("keeps operator docs explicit about the current bulk-reindex scope", () => {
const featureDocs = readRepoFile("docs/features/search.md");
expect(featureDocs).toContain("`kb-articles`, `crm-contacts`, `rows`, and `users`");
expect(featureDocs).toMatch(/Entities still require\s+a dedicated bulk pager/);
});
});
function readRepoFile(path: string): string {
const candidates = [resolve(process.cwd(), path), resolve(process.cwd(), "../..", path)];
const found = candidates.find((candidate) => existsSync(candidate));
if (!found) throw new Error(`Could not find ${path} from ${process.cwd()}`);
return readFileSync(found, "utf8");
}
@@ -0,0 +1,43 @@
import type { SearchIndexSchema } from "./types.js";
/**
* Tasks (AK-P4b). Only list/filter-relevant fields are indexed; reminders,
* watchers and source internals stay in Postgres. The estate-wide `hivegrid-`
* Meili prefix (infra STANDARDS §4) is applied at the runtime adapter layer, so
* the schema name here stays unprefixed like the other indexes.
*/
export const tasksIndex: SearchIndexSchema = {
name: "tasks",
primaryKey: "id",
searchableAttributes: ["title", "description"],
filterableAttributes: [
"tenantId",
"status",
"priority",
"createdByUserId",
"assignedToUserId",
"assignedToGroupId",
"linkedEntityType",
"linkedEntityId",
"archived",
],
sortableAttributes: ["createdAt", "updatedAt", "deadline"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"title",
"description",
"status",
"priority",
"createdByUserId",
"assignedToUserId",
"assignedToGroupId",
"linkedEntityType",
"linkedEntityId",
"archived",
"createdAt",
"updatedAt",
"deadline",
],
};
@@ -0,0 +1,24 @@
/**
* Per-index schema definition. The `tenantId` field is the only attribute
* the wrapper guarantees as a filter — every other property is opt-in per
* domain. Schemas are whitelist-based: documents indexed through these
* definitions only include the explicitly listed fields so PII that the
* domain forgets to exclude does not leak into the index.
*/
export interface SearchIndexSchema {
readonly name: string;
readonly primaryKey: string;
readonly searchableAttributes: readonly string[];
readonly filterableAttributes: readonly string[];
readonly sortableAttributes: readonly string[];
readonly rankingRules?: readonly string[];
readonly stopWords?: readonly string[];
readonly synonyms?: Record<string, readonly string[]>;
/**
* Whitelist of document fields permitted at indexing time. The
* indexer-worker drops any field not listed here before forwarding to
* Meilisearch. Always include `tenantId` and the primary key.
*/
readonly allowedDocumentFields: readonly string[];
}
@@ -0,0 +1,26 @@
import type { SearchIndexSchema } from "./types.js";
/**
* User directory (admin-only). Searchable by name and email but never
* indexes credentials, tokens or 2FA material.
*/
export const usersIndex: SearchIndexSchema = {
name: "users",
primaryKey: "id",
searchableAttributes: ["firstName", "lastName", "email"],
filterableAttributes: ["tenantId", "type", "admin", "active"],
sortableAttributes: ["createdAt", "lastLoginAt"],
rankingRules: ["words", "typo", "proximity", "attribute", "sort", "exactness"],
allowedDocumentFields: [
"id",
"tenantId",
"firstName",
"lastName",
"email",
"type",
"admin",
"active",
"createdAt",
"lastLoginAt",
],
};
@@ -0,0 +1,138 @@
/**
* In-memory fake of the Meilisearch SDK surface area exercised by
* `createSearchClient`. Sufficient for unit and worker-integration tests
* without spinning up a container.
*/
import type { MeiliFactory } from "./client.js";
interface FakeIndex {
documents: Map<string | number, Record<string, unknown>>;
settings: Record<string, unknown>;
primaryKey: string;
}
export interface InMemoryMeiliOptions {
readonly healthStatus?: "available" | "unavailable";
readonly throwOnHealthCheck?: boolean;
readonly throwOnSearch?: boolean;
readonly throwOnIndex?: boolean;
}
export interface InMemoryMeiliState {
readonly indexes: ReadonlyMap<string, FakeIndex>;
options: InMemoryMeiliOptions;
}
export function createInMemoryMeili(options: InMemoryMeiliOptions = {}): {
factory: MeiliFactory;
state: InMemoryMeiliState;
setOption<K extends keyof InMemoryMeiliOptions>(key: K, value: InMemoryMeiliOptions[K]): void;
} {
const indexes = new Map<string, FakeIndex>();
const mutable: { options: InMemoryMeiliOptions } = { options: { ...options } };
const factory: MeiliFactory = () => ({
async createIndex(uid, opts) {
if (mutable.options.throwOnIndex) throw new Error("meili offline");
if (indexes.has(uid)) {
const error = new Error("index_already_exists") as Error & { code: string };
error.code = "index_already_exists";
throw error;
}
indexes.set(uid, { documents: new Map(), settings: {}, primaryKey: opts.primaryKey });
},
index(uid) {
const ensureIndex = (): FakeIndex => {
let idx = indexes.get(uid);
if (!idx) {
idx = { documents: new Map(), settings: {}, primaryKey: "id" };
indexes.set(uid, idx);
}
return idx;
};
return {
async updateSettings(input) {
ensureIndex().settings = { ...ensureIndex().settings, ...input };
},
async search(query, opts) {
if (mutable.options.throwOnSearch) {
const err = new Error("meilisearch search failed") as Error & { code: string };
err.code = "ECONNREFUSED";
throw err;
}
const idx = ensureIndex();
const lowered = query.toLowerCase();
const filter = typeof opts.filter === "string" ? opts.filter : Array.isArray(opts.filter) ? opts.filter.join(" AND ") : "";
const tenantId = extractTenantFromFilter(filter);
const limit = typeof opts.limit === "number" ? opts.limit : 20;
const offset = typeof opts.offset === "number" ? opts.offset : 0;
const hits: Record<string, unknown>[] = [];
for (const doc of idx.documents.values()) {
if (tenantId !== undefined && doc.tenantId !== tenantId) continue;
if (lowered.length > 0 && !documentMatches(doc, lowered)) continue;
hits.push(doc);
}
return {
hits: hits.slice(offset, offset + limit) as unknown as readonly (Record<string, unknown> & { id: string | number })[],
estimatedTotalHits: hits.length,
processingTimeMs: 0,
limit,
offset,
};
},
async addDocuments(documents) {
const idx = ensureIndex();
for (const doc of documents) {
const id = doc[idx.primaryKey];
if (typeof id === "string" || typeof id === "number") {
idx.documents.set(id, doc);
}
}
},
async deleteDocuments(input: readonly (string | number)[] | { filter: string }) {
const idx = ensureIndex();
if (Array.isArray(input)) {
for (const id of input) idx.documents.delete(id);
return;
}
const filter = (input as { filter: string }).filter;
const tenantId = extractTenantFromFilter(filter);
if (tenantId === undefined) return;
for (const [id, doc] of idx.documents) {
if (doc.tenantId === tenantId) idx.documents.delete(id);
}
},
};
},
async health() {
if (mutable.options.throwOnHealthCheck) throw new Error("meilisearch unhealthy");
return { status: mutable.options.healthStatus ?? "available" };
},
});
return {
factory,
state: { indexes, get options() { return mutable.options; } },
setOption(key, value) {
mutable.options = { ...mutable.options, [key]: value };
},
};
}
function documentMatches(doc: Record<string, unknown>, lowered: string): boolean {
for (const value of Object.values(doc)) {
if (typeof value === "string" && value.toLowerCase().includes(lowered)) return true;
if (Array.isArray(value)) {
for (const item of value) {
if (typeof item === "string" && item.toLowerCase().includes(lowered)) return true;
}
}
}
return false;
}
function extractTenantFromFilter(filter: string): string | undefined {
const match = /tenantId\s*=\s*"([^"]+)"/u.exec(filter);
return match ? match[1] : undefined;
}
@@ -0,0 +1,13 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"allowJs": false,
"allowImportingTsExtensions": false,
"lib": ["ES2022"],
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"types": ["node"]
},
"include": ["src/**/*.ts"]
}
@@ -0,0 +1,10 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
include: ["src/**/*.test.ts"],
environment: "node",
globals: false,
reporters: "default",
},
});