Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -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",
],
};