ekklesiaandClaude Opus 5
1e5866504e
ADR 0022 defined what a module UI is and selected React and TypeScript as the authoring model, but closed by recording that it was not buildable end to end: `browser.json` preserves JSX, bundler plugins are denied, and nothing turned a module's `.tsx` into the artifact its manifest declares. This closes exactly that gap. esbuild produces the artifact. It was already the right answer before it was chosen: this workspace resolves esbuild 0.28.1 through Vite/Vitest today and `pnpm-workspace.yaml` already carries `allowBuilds: esbuild`, so the pinned dependency adds no second copy and no new trust decision. It is also the smallest tool that covers TSX, ESM, browser platform, bundling, source maps, and a define-time constant with no plugin ecosystem. Vite library mode would drag in `@vitejs/plugin-react`, which the module boundary denies on purpose; `tsc` alone cannot bundle, so its output would carry bare `react/jsx-runtime` imports no browser resolves. React is bundled, not externalized. That follows from ADR 0022 rather than from convenience: `mount()` was made the ABI precisely so React would not be part of the host contract, and externalizing it would reverse that through the build system — every host would have to supply a compatible React, and a standalone host might not use React at all. The cost is real and accepted: duplicate runtimes and a ~570 KB unminified artifact. Sharing one runtime later is a build optimization that cannot change the contract, because the contract is a mount function. Output is browser ESM at `es2022`, unminified so an operator can review what they install, with `process.env.NODE_ENV` substituted — React reads it at module scope and would otherwise touch a Node global that does not exist in a browser. The output path is read from the module's own manifest rather than a build convention, so declared and produced artifacts cannot drift, and it is validated with the same `packageRelativePathSchema` discovery enforces, so a build can never write where discovery would later reject. `@ekklesia/module-ui-build` owns every option; modules own none. It uses the existing `tooling` role that modules could already depend on, so this pass required no boundary relaxation at all. Its `bin` points at a committed launcher rather than compiled output because pnpm links bins during install, before Turborepo builds anything — a bin targeting `dist/cli.js` fails to link on a fresh clone and breaks every module's UI build in CI. A module with no `entrypoints.ui` is not an error; the CLI reports nothing to build and exits zero, so one script serves both kinds of module. Styling is React inline style objects. A stylesheet import fails the build rather than emitting a sidecar `.css` that no manifest declares and no host loads — an undeclared asset would appear to work in tests and silently do nothing in a real host. `templates/module` is the canonical example and now ships optional UI. Its tests build the artifact from source, validate it with `parseModuleUiExport`, mount it into a real DOM, assert the rendered output, and unmount it; the artifact is rebuilt per run so the proof can never pass against stale output, and `dist/` stays gitignored. Because verify runs both `pnpm test` and `pnpm build`, a UI that cannot be produced fails CI through two independent paths. One correction worth stating plainly: the UI TypeScript project declares `"types": []`, and a UI file referencing `process` does fail in isolation, but TypeScript still pulls Node globals in transitively — a file importing `@ekklesia/module-ui-sdk` reaches `@ekklesia/contracts` and through its Zod and Drizzle types `process.env` typechecks again. The docs and ADR describe this as the convention it is rather than the guard it is not. Core is untouched. Building is an authoring step; discovery still only validates the artifact a module shipped and never executes or produces one. Co-Authored-By: Claude Opus 5 <[email protected]>
2.4 KiB
2.4 KiB
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
.tsxand depend onreact,react-dom, and@ekklesia/module-ui-sdk. Every other UI framework,.jsx, stylesheets, and other presentation formats remain rejected bypnpm boundaries. UI source lives atsrc/ui/index.tsxandpnpm buildcompiles 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, 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.
- 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.