Ekklesia/templates/module/tests/manifest.test.ts

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 backend-only manifest", 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.",
      },
    ]);
    // 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");
  });

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