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,12 @@
import { defineCommand } from "citty";
import { searchReindexCommand } from "./reindex.js";
export const searchCommand = defineCommand({
meta: {
name: "search",
description: "Meilisearch operator commands (bulk reindex via outbox).",
},
subCommands: {
reindex: searchReindexCommand,
},
});
@@ -0,0 +1,75 @@
import { describe, expect, it, vi } from "vitest";
import {
ALL_SEARCH_INDEXES,
BULK_REINDEX_SUPPORTED_INDEXES,
BULK_REINDEX_SUPPORTED_INDEX_NAMES,
crmContactsIndex,
kbArticlesIndex,
rowsIndex,
usersIndex,
} from "@toolctrl/search";
import { enqueueReindexEvents, selectIndexes, selectTenants } from "./reindex.js";
describe("selectIndexes", () => {
it("returns every supported bulk-reindex entry when input is undefined or 'all'", () => {
expect(selectIndexes(undefined)).toEqual(BULK_REINDEX_SUPPORTED_INDEXES);
expect(selectIndexes("all")).toEqual(BULK_REINDEX_SUPPORTED_INDEXES);
expect(selectIndexes("all").map((schema) => schema.name)).toEqual([...BULK_REINDEX_SUPPORTED_INDEX_NAMES]);
});
it("returns the matching schema when a known name is passed", () => {
expect(selectIndexes("kb-articles")).toEqual([kbArticlesIndex]);
expect(selectIndexes("crm-contacts")).toEqual([crmContactsIndex]);
expect(selectIndexes("rows")).toEqual([rowsIndex]);
expect(selectIndexes("users")).toEqual([usersIndex]);
});
it("rejects cataloged indexes that do not have a bulk-reindex pager", () => {
const unsupportedCatalogNames = ALL_SEARCH_INDEXES.map((schema) => schema.name).filter(
(name) => !(BULK_REINDEX_SUPPORTED_INDEX_NAMES as readonly string[]).includes(name)
);
expect(unsupportedCatalogNames).toEqual(["entities"]);
for (const name of unsupportedCatalogNames) {
expect(() => selectIndexes(name)).toThrow(/Unsupported search reindex target/);
}
});
it("throws on unknown index names", () => {
expect(() => selectIndexes("does-not-exist")).toThrow(/Unsupported search reindex target/);
});
});
describe("selectTenants", () => {
it("returns the full list when input is undefined or 'all'", () => {
expect(selectTenants(undefined, ["a", "b"])).toEqual(["a", "b"]);
expect(selectTenants("all", ["a", "b"])).toEqual(["a", "b"]);
});
it("returns the single tenant when a concrete id is passed", () => {
expect(selectTenants("tenant-x", ["a", "b"])).toEqual(["tenant-x"]);
});
});
describe("enqueueReindexEvents", () => {
it("publishes one event per index x tenant", async () => {
const publish = vi.fn().mockResolvedValue(undefined);
const results = await enqueueReindexEvents({
indexes: [kbArticlesIndex],
tenantIds: ["t1", "t2"],
publish,
});
expect(results).toHaveLength(2);
expect(publish).toHaveBeenCalledTimes(2);
expect(publish.mock.calls.map((c) => c[0].tenantId)).toEqual(["t1", "t2"]);
expect(publish.mock.calls[0][0].type).toMatch(/^search\.index\..+\.bulkreindex$/);
expect(publish.mock.calls[0][0].payload).toMatchObject({ action: "bulk-reindex", indexName: kbArticlesIndex.name });
});
it("returns empty list when no tenants provided", async () => {
const publish = vi.fn().mockResolvedValue(undefined);
const results = await enqueueReindexEvents({ indexes: BULK_REINDEX_SUPPORTED_INDEXES, tenantIds: [], publish });
expect(results).toHaveLength(0);
expect(publish).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,116 @@
/**
* `search reindex` — bulk-reindex Meilisearch via the outbox pattern.
*
* Writes `search.index.<entity>.bulkreindex` outbox events for every
* supported (tenant, index) pair selected by the args; the worker-general
* search-indexer consumes them at its own pace and pages over Postgres in
* bounded chunks. No direct Meilisearch traffic from the CLI process —
* operators can run this from a laptop without holding a connection.
*/
import { defineCommand } from "citty";
import consola from "consola";
import { BULK_REINDEX_SUPPORTED_INDEXES, BULK_REINDEX_SUPPORTED_INDEX_NAMES, searchEventType, type SearchIndexSchema } from "@toolctrl/search";
export interface ReindexEnqueueResult {
readonly indexName: string;
readonly tenantId: string;
readonly eventType: string;
}
export interface ReindexEnqueueOptions {
readonly indexes: readonly SearchIndexSchema[];
readonly tenantIds: readonly string[];
/** Outbox publish function — injected by tests, defaults to the
* Prisma-backed implementation at runtime. */
readonly publish: (event: { tenantId: string; type: string; payload: Record<string, unknown> }) => Promise<unknown>;
}
export async function enqueueReindexEvents(options: ReindexEnqueueOptions): Promise<ReindexEnqueueResult[]> {
const results: ReindexEnqueueResult[] = [];
for (const schema of options.indexes) {
for (const tenantId of options.tenantIds) {
const eventType = searchEventType(toEntityName(schema), "bulk-reindex");
await options.publish({
tenantId,
type: eventType,
payload: {
action: "bulk-reindex",
indexName: schema.name,
tenantId,
},
});
results.push({ indexName: schema.name, tenantId, eventType });
}
}
return results;
}
function toEntityName(schema: SearchIndexSchema): string {
// The index name is already the entity slug ("kb-articles", "rows", …)
// so we re-use it; searchEventType strips the dashes.
return schema.name;
}
export function selectIndexes(name: string | undefined): readonly SearchIndexSchema[] {
const supportedNames = BULK_REINDEX_SUPPORTED_INDEX_NAMES.join(", ");
if (!name || name === "all") return BULK_REINDEX_SUPPORTED_INDEXES;
const single = BULK_REINDEX_SUPPORTED_INDEXES.find((schema) => schema.name === name);
if (!single) {
throw new Error(`Unsupported search reindex target "${name}". Supported bulk-reindex indexes: ${supportedNames}.`);
}
return [single];
}
export function selectTenants(input: string | undefined, allTenants: readonly string[]): readonly string[] {
if (!input || input === "all") return allTenants;
return [input];
}
export const searchReindexCommand = defineCommand({
meta: {
name: "reindex",
description: "Enqueue Meilisearch bulk-reindex outbox events.",
},
args: {
tenant: { type: "string", description: "Tenant id, or 'all' for every tenant (default: all)." },
index: { type: "string", description: "Supported index name, or 'all' for every supported index (default: all)." },
},
async run({ args }) {
const tenantArg = args.tenant ? String(args.tenant) : "all";
const indexArg = args.index ? String(args.index) : "all";
const indexes = selectIndexes(indexArg);
// Lazy-load the Prisma-backed publish so the CLI binary does not pull
// in @prisma/client at import time. Imports happen here, inside the
// run handler, after argument parsing.
const [{ getDbClient }, dbOutbox] = await Promise.all([import("@toolctrl/db/client.server"), import("@toolctrl/db/outbox")]);
const prisma = getDbClient();
const tenantIds = await resolveTenantIds(prisma, tenantArg);
if (tenantIds.length === 0) {
consola.warn("No tenants resolved; nothing to do.");
return;
}
const publish = async (event: { tenantId: string; type: string; payload: Record<string, unknown> }) => {
await prisma.$transaction(async (tx: unknown) => {
await dbOutbox.publishOutboxEvent(tx as Parameters<typeof dbOutbox.publishOutboxEvent>[0], {
tenantId: event.tenantId,
type: event.type,
payload: event.payload as Parameters<typeof dbOutbox.publishOutboxEvent>[1]["payload"],
});
});
};
const results = await enqueueReindexEvents({ indexes, tenantIds, publish });
consola.success(`Enqueued ${results.length} bulk-reindex outbox events (${indexes.length} index × ${tenantIds.length} tenant).`);
},
});
async function resolveTenantIds(prisma: unknown, arg: string): Promise<readonly string[]> {
if (arg !== "all") return [arg];
const client = prisma as { tenant: { findMany(args: { select: { id: true } }): Promise<{ id: string }[]> } };
const rows = await client.tenant.findMany({ select: { id: true } });
return rows.map((row) => row.id);
}