ekklesiaandClaude Opus 5
44e676f0df
Two gaps stood between the module UI contract and a host that could use
it. ADR 0023 recorded the first honestly but never diagnosed it: a module
UI file compiled with `"types": []` could still typecheck `process.env`.
The second was simply missing — nothing imported a compiled artifact,
checked its identity, mounted it, or tore it down.
The leak was one type-only import, bisected against the real type graph
rather than guessed. `@ekklesia/module-ui-sdk` imported
`type { EkklesiaPrincipal } from "@ekklesia/contracts"`. Importing
contracts/identity alone is clean and importing Zod alone is clean, but
contracts exposes a single barrel entry, so that one import reached
module-database, whose Drizzle types re-introduce Node's globals. The
runtime was never affected — the import was erased and host-context.js is
`export {}` — but a type-graph leak is still a real boundary failure,
because it silently permits code that cannot run in its target
environment.
The fix is not a narrower import path. The SDK now has no dependencies at
all, so there is no graph to leak through and no future contracts change
can reopen this. It owns `ModuleUiPrincipal`: the same shape ADR 0022
chose, with the Zod brand dropped. That brand encodes a server-side
parsing guarantee a browser cannot produce, and it is the same reason
`permissions.has` already took a plain string. An Ekklesia host still
passes its own `EkklesiaPrincipal` straight through — a branded string is
assignable to `string` — while a standalone host builds the literal.
Proven the way an author experiences it: two fixtures compiled under the
exact project a module uses, one supported and one deliberately reaching
for `process`, with the second required to fail on that specific name.
`@ekklesia/module-ui-host` is the generic loader, in its own package
because the SDK is bundled into every module artifact and host-only
loader code has no business shipping there. The boundary checker enforces
both directions: modules may not depend on the loader, and the loader may
depend only on the SDK plus dev-time tooling.
The distinction that shaped the design: Core resolves `entrypoints.ui` to
an absolute path on the server's disk, and a browser needs a URL. A
loader that accepted the path would test green on a server and fail in
every real host, and would quietly own asset publication. So the loader
takes a browser-loadable URL and knows nothing about how one is obtained.
Ekklesia has no route that publishes installed artifacts, so this is
precisely: loader complete, publication deferred. Nothing can mount an
installed module UI yet, and the docs say so rather than implying
otherwise.
Dynamic import is `(url) => import(url)` with a non-analyzable specifier,
kept as a runtime import so a host does not statically bundle every
installed module or need a hardcoded registry. It is injectable for
bundlers needing their own escape hatch, and deliberately not `eval` or
`new Function`, which would cost a host `unsafe-eval` in its CSP.
Identity is validated through the SDK's existing parser before `mount`
runs, so a stale or mismatched bundle never renders. Contract violations
propagate unwrapped; the loader adds only import and mount failure codes,
sanitized, with the cause attached. Unmount is idempotent, safe when a
module returned no cleanup, and marks an instance unmounted before
running cleanup so a throwing cleanup surfaces once and never re-runs. A
failed mount registers no cleanup. Each instance owns its own state, so
two mounts coexist. The loader never mutates the host's container — not
on success, failure, or unmount.
Tests prove all of it against real module URLs (`data:`, which both
browsers and Node import natively) rather than filesystem paths,
including one artifact built by the canonical Pass 2 pipeline and run
under both an Ekklesia-shaped and a standalone-shaped context. Core,
apps/api, and the contracts package are untouched; discovery remains
inert.
Co-Authored-By: Claude Opus 5 <[email protected]>
71 lines
3.3 KiB
TypeScript
71 lines
3.3 KiB
TypeScript
import { readdir, readFile } from "node:fs/promises";
|
|
import path from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
const sourceDirectory = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
|
|
|
|
async function sourceFiles(): Promise<string[]> {
|
|
const entries = await readdir(sourceDirectory);
|
|
return entries.filter((entry) => entry.endsWith(".ts")).sort();
|
|
}
|
|
|
|
/**
|
|
* This package is bundled into a browser. `@ekklesia/module-sdk` re-exports all of
|
|
* `@ekklesia/contracts`, which pulls Zod, Drizzle, and semver behind one barrel export, so a single
|
|
* value import from a backend package here would drag that whole graph into every module UI bundle
|
|
* (ADR 0022). The dependency on `@ekklesia/contracts` is deliberately type-only and must stay that
|
|
* way; `import type` is erased at build time, a plain `import` is not.
|
|
*/
|
|
describe("module UI SDK stays browser-safe", () => {
|
|
it("imports nothing from another package at all, at type level or runtime", async () => {
|
|
// Stronger than "type-only imports are fine". A type-only import is erased at runtime but still
|
|
// drags the imported package's *type graph* into every consuming program — which is exactly how
|
|
// Node globals reached browser-only module UI before ADR 0024. This package now imports nothing
|
|
// external, so there is no graph to drag.
|
|
for (const file of await sourceFiles()) {
|
|
const source = await readFile(path.join(sourceDirectory, file), "utf8");
|
|
const externalImports = [...source.matchAll(/^(?:import|export)\s[^;]*?from\s+"([^"]+)"/gmu)]
|
|
.map(([, specifier]) => specifier)
|
|
.filter((specifier) => specifier !== undefined && !specifier.startsWith("."));
|
|
|
|
expect(externalImports, `${file} imports outside this package`).toEqual([]);
|
|
}
|
|
});
|
|
|
|
it("declares no dependencies whatsoever", async () => {
|
|
const manifestPath = path.join(sourceDirectory, "..", "package.json");
|
|
const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
|
|
dependencies?: Record<string, string>;
|
|
peerDependencies?: Record<string, string>;
|
|
};
|
|
|
|
expect(Object.keys(manifest.dependencies ?? {})).toEqual([]);
|
|
expect(Object.keys(manifest.peerDependencies ?? {})).toEqual([]);
|
|
});
|
|
|
|
it("does not depend on a UI framework, so the contract stays framework-neutral", async () => {
|
|
const manifestPath = path.join(sourceDirectory, "..", "package.json");
|
|
const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
|
|
dependencies?: Record<string, string>;
|
|
devDependencies?: Record<string, string>;
|
|
peerDependencies?: Record<string, string>;
|
|
};
|
|
const declared = [
|
|
...Object.keys(manifest.dependencies ?? {}),
|
|
...Object.keys(manifest.devDependencies ?? {}),
|
|
...Object.keys(manifest.peerDependencies ?? {}),
|
|
];
|
|
|
|
// React is the supported way to *author* module UI. It is deliberately absent from the host
|
|
// contract, so a host never has to match a module's rendering library.
|
|
for (const framework of ["react", "react-dom", "vue", "svelte", "preact"]) {
|
|
expect(declared).not.toContain(framework);
|
|
}
|
|
// Backend graphs must not reappear through a development dependency either.
|
|
for (const backend of ["drizzle-orm", "zod", "semver", "@ekklesia/contracts"]) {
|
|
expect(declared).not.toContain(backend);
|
|
}
|
|
});
|
|
});
|