237 lines
10 KiB
TypeScript
237 lines
10 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
import { readFile } from "node:fs/promises";
|
|
import {
|
|
ANONYMOUS_PRINCIPAL,
|
|
type CapabilityId,
|
|
EMPTY_MODULE_CONFIGURATION,
|
|
EMPTY_MODULE_STORAGE,
|
|
type ModuleConfiguration,
|
|
type ModuleDatabase,
|
|
type ModuleRouteDefinitionInput,
|
|
type ModuleRouteHandlerContext,
|
|
type ModuleRuntimeServices,
|
|
parseDrizzleMigrationJournal,
|
|
parseModuleManifest,
|
|
parseModuleMigrationPolicy,
|
|
type RegisteredCapability,
|
|
} from "@ekklesia/module-sdk";
|
|
import { getTableConfig } from "drizzle-orm/pg-core";
|
|
import { describe, expect, it } from "vitest";
|
|
import moduleSchema, { records } from "../src/schema/index.js";
|
|
import moduleRuntime, { recordsCapability } from "../src/server/index.js";
|
|
|
|
/** A small typed fake `ModuleDatabase` — no PostgreSQL required for this unit test, which only
|
|
* proves the example handler queries through the facade and shapes its response correctly. */
|
|
function fakeModuleDatabase(rows: readonly { id: string; value: string }[]): ModuleDatabase {
|
|
const selectBuilder = { from: () => Promise.resolve(rows) };
|
|
return { select: () => selectBuilder } as unknown as ModuleDatabase;
|
|
}
|
|
|
|
async function registerAndCaptureRoutes(): Promise<{
|
|
provided: Map<CapabilityId, unknown>;
|
|
routes: ModuleRouteDefinitionInput[];
|
|
}> {
|
|
const provided = new Map<CapabilityId, unknown>();
|
|
const routes: ModuleRouteDefinitionInput[] = [];
|
|
await moduleRuntime.register?.({
|
|
// The template declares no configuration, so it receives an empty snapshot — proof that a
|
|
// backend module needing no settings stays exactly as simple as it was (ADR 0029).
|
|
config: EMPTY_MODULE_CONFIGURATION,
|
|
capabilities: {
|
|
provide(capabilityId, implementation) {
|
|
provided.set(capabilityId, implementation);
|
|
},
|
|
resolve(_capabilityId: CapabilityId): RegisteredCapability | undefined {
|
|
return undefined;
|
|
},
|
|
},
|
|
http: {
|
|
route(definition) {
|
|
routes.push(definition);
|
|
},
|
|
},
|
|
moduleId: "example",
|
|
// The template deliberately declares no realtime channel, proving modules opt in rather than
|
|
// receiving a mandatory feature-specific scaffold.
|
|
realtime: { channel: () => undefined },
|
|
});
|
|
return { provided, routes };
|
|
}
|
|
|
|
describe("module template", () => {
|
|
it("ships a valid product manifest with independently declared primary and display UI", async () => {
|
|
const manifestUrl = new URL("../ekklesia.module.json", import.meta.url);
|
|
const manifestInput = JSON.parse(await readFile(manifestUrl, "utf8")) as unknown;
|
|
const manifest = parseModuleManifest(manifestInput);
|
|
|
|
expect(manifest.id).toBe("example");
|
|
expect(manifest.capabilities).toEqual([{ id: "example.records", version: "1.0.0" }]);
|
|
expect(manifest.permissions).toEqual([
|
|
{
|
|
id: "example.records.read",
|
|
baseline: "restricted",
|
|
description: "Read example records.",
|
|
},
|
|
{
|
|
id: "example.display.view",
|
|
baseline: "restricted",
|
|
description: "View the example full-screen display.",
|
|
},
|
|
]);
|
|
// The template declares **no** logical storage bucket, deliberately. Since ADR 0030 a declared
|
|
// bucket is a real requirement: a module that declares one is blocked on an installation with no
|
|
// object-storage provider. A starting point that could not run without S3 configured would be a
|
|
// poor starting point, so storage is something a module author opts into.
|
|
expect(manifest.storage.buckets).toEqual([]);
|
|
expect(manifest.entrypoints.schema).toBe("./dist/schema/index.js");
|
|
expect(manifest.entrypoints.migrations).toBe("./drizzle");
|
|
expect(manifest.entrypoints.ui).toBe("./dist/ui/index.js");
|
|
expect(manifest.entrypoints.display).toEqual({
|
|
artifact: "./dist/display/index.js",
|
|
permission: "example.display.view",
|
|
});
|
|
});
|
|
|
|
it("packages a generated stable Drizzle migration and matching policy", async () => {
|
|
const [journalInput, policyInput, packageInput, sql] = await Promise.all([
|
|
readFile(new URL("../drizzle/meta/_journal.json", import.meta.url), "utf8"),
|
|
readFile(new URL("../drizzle/meta/_ekklesia.json", import.meta.url), "utf8"),
|
|
readFile(new URL("../package.json", import.meta.url), "utf8"),
|
|
readFile(new URL("../drizzle/0000_initial.sql", import.meta.url)),
|
|
]);
|
|
const journal = parseDrizzleMigrationJournal(JSON.parse(journalInput) as unknown);
|
|
const policy = parseModuleMigrationPolicy(JSON.parse(policyInput) as unknown);
|
|
const packageJson = JSON.parse(packageInput) as {
|
|
devDependencies?: Record<string, string>;
|
|
files?: string[];
|
|
};
|
|
|
|
expect(journal.entries.map((entry) => entry.tag)).toEqual(["0000_initial"]);
|
|
expect(policy).toMatchObject({
|
|
moduleId: "example",
|
|
entries: [{ tag: "0000_initial", destructive: { mode: "none" } }],
|
|
});
|
|
expect(packageJson.devDependencies?.["drizzle-kit"]).toBe("0.31.10");
|
|
expect(packageJson.files).toContain("drizzle");
|
|
expect(createHash("sha256").update(sql).digest("hex")).toBe(
|
|
"e09d6c9995fa2c4bd59b815afc9bb6ded6a2d4e1b3e1d97c10457a94a6a4f2a4",
|
|
);
|
|
expect(sql.toString("utf8")).toContain('CREATE TABLE "example_records"');
|
|
});
|
|
|
|
it("exports the typed runtime definition used by the compiled server entrypoint, registering its one example route database-free", async () => {
|
|
const { provided, routes } = await registerAndCaptureRoutes();
|
|
|
|
expect(moduleRuntime).toMatchObject({ id: "example", version: "0.1.0" });
|
|
expect(provided.get("example.records")).toBe(recordsCapability);
|
|
expect(routes).toHaveLength(1);
|
|
expect(routes[0]).toMatchObject({
|
|
method: "GET",
|
|
path: "/records",
|
|
permission: "example.records.read",
|
|
// The template's example route demonstrates the explicit no-body contract: a GET route
|
|
// accepts no request body at all.
|
|
maxBodyBytes: 0,
|
|
});
|
|
});
|
|
|
|
it("queries the module's own table through context.services.database in the example route handler", async () => {
|
|
const { routes } = await registerAndCaptureRoutes();
|
|
const route = routes[0];
|
|
if (!route) {
|
|
throw new Error("Expected the example route to be registered.");
|
|
}
|
|
|
|
const fakeRows = [{ id: "9d3f9f7e-3b1a-4c9a-8b8e-2b6b1e6f9a11", value: "hello" }];
|
|
const services: ModuleRuntimeServices = Object.freeze({
|
|
database: fakeModuleDatabase(fakeRows),
|
|
});
|
|
const context: ModuleRouteHandlerContext = Object.freeze({
|
|
config: EMPTY_MODULE_CONFIGURATION,
|
|
moduleId: "example",
|
|
params: Object.freeze({}),
|
|
principal: ANONYMOUS_PRINCIPAL,
|
|
realtime: { publish: () => undefined },
|
|
services,
|
|
// The template declares no logical bucket, so it receives storage that refuses every one —
|
|
// present rather than `undefined`, so module code never branches on whether the host has it.
|
|
storage: EMPTY_MODULE_STORAGE,
|
|
});
|
|
|
|
const response = await route.handler(new Request("http://localhost/records"), context);
|
|
|
|
expect(response).toBeInstanceOf(Response);
|
|
// With no configuration supplied, the handler falls back to the same default the manifest
|
|
// declares. In a real Ekklesia deployment that fallback is unreachable — the platform resolves
|
|
// the declared default before any module code runs — but the accessor is typed `T | undefined`
|
|
// for undeclared keys, so module code still writes it.
|
|
expect(await response.json()).toEqual([{ ...fakeRows[0], value: "Hello, hello" }]);
|
|
});
|
|
|
|
it("reads its own declared configuration through context.config, never the environment", async () => {
|
|
const { routes } = await registerAndCaptureRoutes();
|
|
const route = routes[0];
|
|
if (!route) {
|
|
throw new Error("Expected the example route to be registered.");
|
|
}
|
|
|
|
const fakeRows = [{ id: "9d3f9f7e-3b1a-4c9a-8b8e-2b6b1e6f9a11", value: "hello" }];
|
|
// A hand-rolled `ModuleConfiguration`: it is a `@ekklesia/contracts` interface, and a module may
|
|
// never import Core, so this is what a module-layer test can legitimately construct. It also
|
|
// demonstrates the portability claim directly — the host that produces this object could be
|
|
// Ekklesia, or a future standalone host reading YAML, and this module cannot tell.
|
|
const config: ModuleConfiguration = Object.freeze({
|
|
get: (key: string) => (key === "greeting" ? "Welcome" : undefined),
|
|
getBoolean: () => undefined,
|
|
getEnum: () => undefined,
|
|
getInteger: () => undefined,
|
|
getSecret: () => undefined,
|
|
getString: (key: string) => (key === "greeting" ? "Welcome" : undefined),
|
|
getUrl: () => undefined,
|
|
has: (key: string) => key === "greeting",
|
|
keys: () => Object.freeze(["greeting"]),
|
|
});
|
|
const context: ModuleRouteHandlerContext = Object.freeze({
|
|
config,
|
|
moduleId: "example",
|
|
params: Object.freeze({}),
|
|
principal: ANONYMOUS_PRINCIPAL,
|
|
realtime: { publish: () => undefined },
|
|
services: Object.freeze({ database: fakeModuleDatabase(fakeRows) }),
|
|
storage: EMPTY_MODULE_STORAGE,
|
|
});
|
|
|
|
const response = await route.handler(new Request("http://localhost/records"), context);
|
|
|
|
expect(await response.json()).toEqual([{ ...fakeRows[0], value: "Welcome, hello" }]);
|
|
});
|
|
|
|
it("declares exactly one configuration key, with a default, and no secret", async () => {
|
|
const manifestUrl = new URL("../ekklesia.module.json", import.meta.url);
|
|
const manifest = parseModuleManifest(
|
|
JSON.parse(await readFile(manifestUrl, "utf8")) as unknown,
|
|
);
|
|
|
|
// The template stays the smallest thing that demonstrates the contract: one ordinary key with a
|
|
// safe default. A backend module needing no settings omits `configuration` entirely and remains
|
|
// valid, which the manifest schema's own default proves.
|
|
expect(manifest.configuration).toEqual([
|
|
{
|
|
default: "Hello",
|
|
description: "Prefix this module puts in front of a record value.",
|
|
key: "greeting",
|
|
maxLength: 120,
|
|
required: false,
|
|
type: "string",
|
|
},
|
|
]);
|
|
expect(manifest.configuration.some((entry) => entry.type === "secret")).toBe(false);
|
|
});
|
|
|
|
it("exports a namespaced module-owned Drizzle schema", () => {
|
|
expect(moduleSchema.moduleId).toBe("example");
|
|
expect(moduleSchema.tables.records).toBe(records);
|
|
expect(getTableConfig(records)).toMatchObject({ name: "example_records", schema: undefined });
|
|
});
|
|
});
|