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,447 @@
import { afterEach, describe, expect, test, vi } from "vitest";
import { z } from "zod";
import {
PLUGIN_HOOK_ENTITY_CREATED,
PLUGIN_HOOK_ENTITY_DELETED,
PLUGIN_HOOK_ENTITY_UPDATED,
PLUGIN_HOOK_TENANT_CREATED,
PLUGIN_HOOK_USER_CREATED,
PLUGIN_HOOK_WORKFLOW_CREATED,
PLUGIN_HOOK_WORKFLOW_DELETED,
PLUGIN_HOOK_WORKFLOW_EXECUTED,
PLUGIN_HOOK_WORKFLOW_FAILED,
PLUGIN_HOOK_WORKFLOW_UPDATED,
PLUGIN_PRODUCTION_AVAILABLE_HOOK_NAMES,
__resetPluginHookRegistryForTests,
getPluginHook,
getUnavailablePluginHookNames,
isPluginHookProductionAvailable,
listPluginHooks,
registerHook,
validatePluginHookPayload,
} from "./registry.js";
import { PluginHookValidationError, emitPluginHook } from "./emit.js";
afterEach(() => {
__resetPluginHookRegistryForTests();
});
describe("plugin hook registry", () => {
test("registers the foundation hooks", () => {
const hooks = listPluginHooks().map((h) => h.name).sort();
expect(hooks).toContain("tenant.created");
expect(hooks).toContain("user.created");
expect(hooks).toContain("entity.created");
expect(hooks).toContain("entity.updated");
expect(hooks).toContain("entity.deleted");
expect(hooks).toContain("workflow.created");
expect(hooks).toContain("workflow.updated");
expect(hooks).toContain("workflow.deleted");
expect(hooks).toContain("workflow.executed");
expect(hooks).toContain("workflow.failed");
});
test("each hook has an outboxEventType matching plugin.hook.<name>", () => {
for (const hook of listPluginHooks()) {
expect(hook.outboxEventType).toBe(`plugin.hook.${hook.name}`);
// Must conform to the outbox eventType pattern.
expect(hook.outboxEventType).toMatch(/^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*){2,}$/u);
}
});
test("marks only foundation hooks as production-available", () => {
expect(PLUGIN_PRODUCTION_AVAILABLE_HOOK_NAMES).toEqual([
"tenant.created",
"user.created",
"entity.created",
"entity.updated",
"entity.deleted",
"workflow.created",
"workflow.updated",
"workflow.deleted",
"workflow.executed",
"workflow.failed",
]);
expect(isPluginHookProductionAvailable("tenant.created")).toBe(true);
expect(isPluginHookProductionAvailable("workflow.failed")).toBe(true);
registerHook({
name: "billing.paid",
outboxEventType: "plugin.hook.billing.paid",
payloadSchema: z.object({ invoiceId: z.string() }),
});
expect(getPluginHook("billing.paid")).toBeDefined();
expect(isPluginHookProductionAvailable("billing.paid")).toBe(false);
expect(getUnavailablePluginHookNames([{ name: "tenant.created" }, { name: "billing.paid" }, "billing.paid", "unknown.hook"])).toEqual([
"billing.paid",
]);
});
test("getPluginHook returns the registered definition", () => {
expect(getPluginHook("tenant.created")).toBe(PLUGIN_HOOK_TENANT_CREATED);
expect(getPluginHook("unknown")).toBeUndefined();
});
test("validates a well-formed tenant.created payload", () => {
const result = validatePluginHookPayload(PLUGIN_HOOK_TENANT_CREATED, {
tenantId: "t-1",
slug: "acme",
ownerEmail: "owner@example.com",
plan: "free",
createdAt: "2026-05-17T10:00:00.000Z",
});
expect(result.ok).toBe(true);
});
test("rejects payload missing required fields", () => {
const result = validatePluginHookPayload(PLUGIN_HOOK_USER_CREATED, {
email: "u@example.com",
});
expect(result.ok).toBe(false);
if (!result.ok) {
expect(result.issues.length).toBeGreaterThan(0);
}
});
test("entity.* hooks accept the canonical payload", () => {
const payload = {
entityType: "row",
entityId: "row-1",
tenantId: "t-1",
userId: "u-1",
occurredAt: "2026-05-17T10:00:00.000Z",
};
expect(validatePluginHookPayload(PLUGIN_HOOK_ENTITY_CREATED, payload).ok).toBe(true);
expect(validatePluginHookPayload(PLUGIN_HOOK_ENTITY_UPDATED, { ...payload, changedFields: ["a"] }).ok).toBe(true);
expect(validatePluginHookPayload(PLUGIN_HOOK_ENTITY_DELETED, payload).ok).toBe(true);
});
test("rejects raw or sensitive fields on public hook payloads", () => {
expect(
validatePluginHookPayload(PLUGIN_HOOK_TENANT_CREATED, {
tenantId: "t-1",
slug: "acme",
ownerEmail: "owner@example.com",
plan: "free",
createdAt: "2026-05-17T10:00:00.000Z",
rawPayload: { billingEmail: "billing@example.com" },
}).ok
).toBe(false);
expect(
validatePluginHookPayload(PLUGIN_HOOK_USER_CREATED, {
userId: "u-1",
tenantId: "t-1",
email: "u@example.com",
locale: "en",
createdAt: "2026-05-17T10:00:00.000Z",
passwordHash: "secret",
}).ok
).toBe(false);
expect(
validatePluginHookPayload(PLUGIN_HOOK_ENTITY_CREATED, {
entityType: "row",
entityId: "row-1",
tenantId: "t-1",
userId: "u-1",
beforeData: { apiKey: "secret" },
occurredAt: "2026-05-17T10:00:00.000Z",
}).ok
).toBe(false);
});
test("workflow.executed validates terminal tenant-scoped execution metadata without payload bodies", () => {
const valid = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
userId: "user_1",
type: "trigger",
status: "success",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(valid.ok).toBe(true);
const legacyWithoutUserId = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "success",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(legacyWithoutUserId.ok).toBe(true);
const systemExecution = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
userId: null,
type: "trigger",
status: "success",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(systemExecution.ok).toBe(true);
const withLeakedOutput = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
userId: "user_1",
type: "trigger",
status: "success",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
output: { secret: "nope" },
});
expect(withLeakedOutput.ok).toBe(false);
const waiting = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "manual",
status: "waitingBlock",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(waiting.ok).toBe(false);
const withRawError = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
userId: "user_1",
type: "trigger",
status: "error",
durationMs: 12,
errorCode: "workflow_execution_failed",
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
error: "Provider failed with token=sk_live_secret",
});
expect(withRawError.ok).toBe(false);
const successWithErrorCode = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "success",
durationMs: 12,
errorCode: "workflow_execution_failed",
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(successWithErrorCode.ok).toBe(false);
const errorWithoutCode = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_EXECUTED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "error",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(errorWithoutCode.ok).toBe(false);
});
test("workflow.failed validates failure-only execution metadata without raw error bodies", () => {
const valid = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_FAILED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "error",
durationMs: 12,
errorCode: "workflow_execution_failed",
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(valid.ok).toBe(true);
const successfulExecution = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_FAILED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "success",
durationMs: 12,
errorCode: "workflow_execution_failed",
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(successfulExecution.ok).toBe(false);
const withoutCode = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_FAILED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "error",
durationMs: 12,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
});
expect(withoutCode.ok).toBe(false);
const withRawError = validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_FAILED, {
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
type: "trigger",
status: "error",
durationMs: 12,
errorCode: "workflow_execution_failed",
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
error: "Provider failed with token=sk_live_secret",
});
expect(withRawError.ok).toBe(false);
});
test("workflow definition hooks validate metadata without workflow bodies", () => {
const payload = {
tenantId: "tenant_1",
workflowId: "workflow_1",
userId: "user_1",
status: "draft",
appliesToAllTenants: false,
occurredAt: "2026-05-26T20:00:00.000Z",
};
expect(validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_CREATED, payload).ok).toBe(true);
expect(
validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_UPDATED, {
...payload,
status: "live",
changedFields: ["status"],
}).ok
).toBe(true);
expect(
validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_DELETED, {
...payload,
tenantId: null,
userId: null,
appliesToAllTenants: true,
}).ok
).toBe(true);
expect(
validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_UPDATED, {
...payload,
changedFields: ["blocks"],
blocks: [{ id: "block_1", input: { token: "secret" } }],
}).ok
).toBe(false);
expect(
validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_CREATED, {
...payload,
credentials: { apiKey: "secret" },
}).ok
).toBe(false);
expect(
validatePluginHookPayload(PLUGIN_HOOK_WORKFLOW_CREATED, {
...payload,
input: { raw: true },
}).ok
).toBe(false);
});
test("registerHook rejects duplicate name", () => {
expect(() =>
registerHook({
name: "tenant.created",
outboxEventType: "plugin.hook.tenant.created",
payloadSchema: z.object({}),
})
).toThrow(/already registered/u);
});
test("registerHook rejects malformed outboxEventType", () => {
expect(() =>
registerHook({
name: "custom.singleword",
// missing second dot-segment after plugin.hook
outboxEventType: "plugin.hook.singleword" as `plugin.hook.${string}`,
payloadSchema: z.object({}),
})
).toThrow(/must end in/u);
});
test("registerHook rejects malformed or mismatched hook names", () => {
expect(() =>
registerHook({
name: "Tenant.created",
outboxEventType: "plugin.hook.tenant.created",
payloadSchema: z.object({}),
})
).toThrow(/lower-case dotted/u);
expect(() =>
registerHook({
name: "billing.invoice.paid",
outboxEventType: "plugin.hook.billing.invoice.created",
payloadSchema: z.object({}),
})
).toThrow(/must match hook name/u);
expect(getPluginHook("billing.invoice.paid")).toBeUndefined();
});
});
describe("emitPluginHook", () => {
test("publishes a validated outbox event for a valid payload", async () => {
const publish = vi.fn().mockResolvedValue({ id: "evt-1" });
await emitPluginHook(
{ fake: "tx" },
PLUGIN_HOOK_TENANT_CREATED,
{
tenantId: "t-1",
slug: "acme",
ownerEmail: "owner@example.com",
plan: "free",
createdAt: "2026-05-17T10:00:00.000Z",
},
publish,
{ tenantId: "t-1", dispatchKey: "tenant:t-1:created" }
);
expect(publish).toHaveBeenCalledOnce();
const args = publish.mock.calls[0]?.[1] as { type: string; tenantId: string | null; dispatchKey: string | null };
expect(args.type).toBe("plugin.hook.tenant.created");
expect(args.tenantId).toBe("t-1");
expect(args.dispatchKey).toBe("tenant:t-1:created");
});
test("throws PluginHookValidationError when payload is invalid", async () => {
const publish = vi.fn();
await expect(
emitPluginHook(
{},
PLUGIN_HOOK_USER_CREATED,
{ email: "not-an-email" } as never,
publish
)
).rejects.toBeInstanceOf(PluginHookValidationError);
expect(publish).not.toHaveBeenCalled();
});
});