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,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;
}