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,108 @@
/**
* Phase 06 #22 — Plugin hook emission helper.
*
* Wraps `publishOutboxEvent` so host call-sites stay one-line:
*
* await emitPluginHook(tx, PLUGIN_HOOK_TENANT_CREATED, payload);
*
* The helper:
* 1. Validates the payload against the registered Zod schema.
* 2. Publishes a `plugin.hook.<name>` outbox event inside the
* surrounding Prisma transaction (atomic with the host write).
* 3. Returns the persisted OutboxEvent row so callers can correlate
* it in audit logs.
*
* Bad payloads throw {@link PluginHookValidationError} — callers MUST
* either handle it (when the payload is user-derived) or let it
* propagate so the host write rolls back.
*
* Subscriber resolution + fan-out into one outbox row per installed
* plugin is intentionally deferred to the worker side: a single
* `plugin.hook.<name>` event lands in the outbox queue and the
* downstream consumer (worker) expands it into per-plugin invocations.
* This keeps the producer path (web request) cheap and avoids
* coupling the request thread to the Plugin table.
*/
import type { z } from "zod";
import {
validatePluginHookPayload,
type PluginHookDefinition,
} from "./registry.js";
/**
* JSON-compatible value type, structurally identical to
* `Prisma.InputJsonValue` without taking the dependency on
* `@toolctrl/db` (which would cycle through the worker bootstrap).
*/
export type PluginHookJsonValue =
| string
| number
| boolean
| null
| { [key: string]: PluginHookJsonValue }
| ReadonlyArray<PluginHookJsonValue>;
export class PluginHookValidationError extends Error {
public override readonly name = "PluginHookValidationError";
public readonly hookName: string;
public readonly issues: ReadonlyArray<z.ZodIssue>;
constructor(hookName: string, issues: ReadonlyArray<z.ZodIssue>) {
super(`Invalid payload for plugin hook '${hookName}': ${JSON.stringify(issues)}`);
this.hookName = hookName;
this.issues = issues;
}
}
/**
* Minimal publish surface — kept identical to the @toolctrl/db helper
* so this package does not have to depend on @toolctrl/db directly
* (avoids a cycle with the worker bootstrap that pulls plugin-runtime
* via @toolctrl/db).
*/
export type PluginHookOutboxPublisher = (
tx: unknown,
args: {
tenantId?: string | null;
type: string;
payload: PluginHookJsonValue;
dispatchKey?: string | null;
}
) => Promise<unknown>;
export type EmitPluginHookOptions = {
tenantId?: string | null;
/**
* Optional idempotency key. When two writers might emit the same
* hook for the same business object (e.g. two onboarding paths both
* creating the same tenant) supplying a stable key prevents
* duplicate downstream invocations.
*/
dispatchKey?: string | null;
};
/**
* Validate + publish a plugin-hook outbox event inside a transaction.
* The transaction client is intentionally typed as `unknown` so this
* package keeps zero runtime dependency on @toolctrl/db — the caller
* (a `.server.ts` file in apps/web) already imports the prisma types
* and passes the correct shape.
*/
export async function emitPluginHook<TPayload>(
tx: unknown,
def: PluginHookDefinition<TPayload>,
payload: TPayload,
publish: PluginHookOutboxPublisher,
options: EmitPluginHookOptions = {}
): Promise<void> {
const validation = validatePluginHookPayload(def, payload);
if (!validation.ok) {
throw new PluginHookValidationError(def.name, validation.issues);
}
await publish(tx, {
tenantId: options.tenantId ?? null,
type: def.outboxEventType,
payload: validation.payload as unknown as PluginHookJsonValue,
dispatchKey: options.dispatchKey ?? null,
});
}