Zayin/Ekklesia

Fork 0

Files

T

ekklesiaandClaude Opus 5 616c1d4834

CI / verify (pull_request) Successful in 34s

Details

CI / infrastructure-smoke (pull_request) Successful in 21s

Details

CI / migration-smoke (pull_request) Successful in 43s

Details

feat: mount discovered module UI in a minimal Ekklesia browser host

Phase 6C pass 2. Every link in the module UI chain existed except the one
that closes it: a module could be authored, built, validated, published at a
browser URL, and loaded by a generic loader — and nothing in Ekklesia did any
of it. There was no browser application at all.

Two pieces were missing. A browser could not discover what to mount, and it
must not work that out for itself.

GET /api/v1/module-ui is the inventory: per publishable module, its id and
version, the server-produced artifact URL, the server-produced root of the
module's own API, and the subset of that module's declared permissions the
caller holds. Five fields, each because building a ModuleUiHostContext needs
it — no filesystem paths, and no name/icon/folder/order, because navigation
metadata is a design that does not exist yet. Its module set is the ADR 0025
publication registry rather than a rescan, so the inventory and the artifact
route cannot disagree. It requires a new Core permission, core.modules.ui.read
(baseline authenticated), because it is precisely the enumeration the anonymous
artifact route deliberately withholds.

Both URLs are server-produced. moduleUiArtifactUrl already existed;
moduleApiBaseUrl is now exported and moduleRoutePath builds on it, so each URL
shape has exactly one author. Without it the shell would hardcode
/api/v1/modules/<id> — the prefix ADR 0022 forbids a module UI from spelling,
reappearing in the host instead.

surfaces/shell (@ekklesia/shell) is the repository's first surface: a small
React application built to static files by its own esbuild script. It resolves
the principal, fetches the inventory, builds the host context entirely from
server-derived data, and hands the artifact URL to @ekklesia/module-ui-host.
One frame per selection — keyed by module identity — defeats the stale-load
race; the host owns the container, the loading state, and every failure, so a
broken module costs its own panel rather than the shell.

The shell statically imports no module, and both levels are checked: no source
import may name a module, and the emitted bundle must contain exactly one
dynamic import (the loader's) with no module id, no /api/v1/modules, no eval,
and no blob URL. Permission hints come from Core's own evaluator and stay
presentation-only — the end-to-end test has a UI holding no grant call its API
anyway and still receive 403.

Surfaces may now depend only on browser-safe shared roles; @ekklesia/contracts
is deliberately excluded, since its barrel pulls Drizzle's types and Node's
globals into the browser — the hole ADR 0024 closed one layer down.

Not the Dashboard: no navigation, grouping, icons, ordering, design system, or
routing. The selector is a list of module ids.

Co-Authored-By: Claude Opus 5 <[email protected]>

2026-08-22 08:55:44 -05:00

2.9 KiB

Raw Blame History

Contributing

Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency boundaries described in repository-boundaries.md.

Before opening a change, run:

pnpm verify

Migration-runner changes also require the disposable live PostgreSQL suite:

pnpm test:migrations:integration

See the testing guide for the distinction between unit and live evidence and for credential-safe troubleshooting.

When adding or changing a module manifest, also run pnpm modules:validate directly for focused, path-aware discovery errors. It is included in pnpm verify.

If Docker is available, also validate the development infrastructure:

pnpm infrastructure:config

Package rules

Use strict TypeScript for production packages.
Expose supported entry points through package exports; do not import another package's private source paths.
Use workspace: ranges for internal package dependencies.
Modules own their own UI and author it in React and TypeScript (ADR 0022). A module package may contain .tsx and depend on react, react-dom, and @ekklesia/module-ui-sdk. Every other UI framework, .jsx, stylesheets, and other presentation formats remain rejected by pnpm boundaries. UI source lives at src/ui/index.tsx and pnpm build compiles it to the artifact the manifest declares, via @ekklesia/module-ui-build (ADR 0023) — module authors write no bundler configuration. Styling is React inline style objects only for now, and no host mounts a UI entrypoint yet.
Module UI reaches its host only through @ekklesia/module-ui-sdk — never @ekklesia/module-ui-host, which is the host-side loader — and asks the host for its own API by relative path — never by constructing /api/v1/modules/<id>/..., which is Ekklesia's private deployment detail and would break standalone hosting.
The containing application shell, navigation, global theme, and platform policy belong to Core and the host application, never to a module. Ekklesia's own shell is surfaces/shell; it discovers installed module UIs through GET /api/v1/module-ui and mounts them with @ekklesia/module-ui-host, and it statically imports no module (ADR 0026).
A surface is browser code. It may depend on browser-safe shared roles only — never @ekklesia/contracts or @ekklesia/module-sdk, whose type graphs pull Node's globals into the browser — and it reaches the server over HTTP.
Add or update tests when changing a contract or architectural rule.
Record major architectural changes in an ADR rather than burying them in an implementation.

Runtime registries and aggregate schemas will be produced by later phases. Do not add a manually maintained feature-module registry; discovery starts from validated ekklesia.module.json files.

2.9 KiB Raw Blame History

Contributing

Package rules

2.9 KiB

Raw Blame History