feat: let one module contribute a browser renderer to another's capability
The platform has had a complete story for one module using another's
*backend* since ADR 0006 — capabilities, versioned ranges, provider
registration. It has had none at all for one module using another's *browser*
code, and every workaround is wrong in a way that matters: a consumer cannot
import a peer module, it cannot re-implement a renderer for a domain it does
not own, and a second `entrypoints` role would put the platform in charge of
deciding when a slot inside someone else's screen should be filled.
Add a generic browser contribution. `manifestVersion: 7` declares one:
namespaced id, its own version, a target capability, a compatible range, and
one artifact. That is the complete list, and the omissions are the decision —
no payload schema, slot, ordering, or rendering hint exists anywhere, so Core
cannot learn what a slide is because the declaration cannot express it.
Discovery resolves a contribution artifact through the *identical* loop every
other compiled entrypoint uses, inheriting the path, containment, symlink,
extension, and file-kind checks rather than getting a weaker copy of them. The
registry publishes one only when another eligible module provides the target
capability within the declared range; otherwise it is absent rather than
mounted and broken. `apps/api` serves it as a sibling of the artifact and
display routes, with the same policy: three lookup keys, one exact match, one
already-validated path, and one indistinguishable 404 for unknown, undeclared,
stale, and incompatible alike.
A consumer discovers through the host, never through a URL. Its descriptor
carries identity, version, and capability; the URL stays server-side and is
resolved exactly as `api.request("records")` is. A module can only ever see
contributions aimed at a capability it itself provides, and cannot name its
way to anything else — a mount for a withheld id fails without fetching.
The consumer owns the domain contract entirely. Input is opaque JSON, checked
structurally so a Date, a function, a cycle, or `undefined` fails at the
boundary rather than vanishing somewhere far from the mistake, and checked for
nothing else. A contributed renderer receives its own id and that input: no
API client, realtime, principal, configuration, database, storage, or
credential. Loading one grants its module nothing.
The contribution ABI is versioned separately from the module UI ABI, because
the two have different shapes and lifecycles and coupling them would force
every module to rebuild whenever either moved. It supports asynchronous
readiness, update-without-remount (a screen that remounted per tick would
restart animations and reload media), deterministic cleanup in a `finally`,
and sanitized failure that never carries the consumer's domain data. Each
renderer mounts in its own isolated root with its own stylesheet.
The template now declares a contribution, so `pnpm build` exercises the whole
authoring path, and the shell suite drives the full relationship — one module
discovering, mounting, updating, and unmounting another's React renderer with
neither importing the other.
Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
07835b7b56
commit
c444ff570b
@@ -1,6 +1,11 @@
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { moduleDisplayEntrypointSchema, packageRelativePathSchema } from "@ekklesia/contracts";
|
||||
import {
|
||||
contributionLocalName,
|
||||
moduleContributionDeclarationSchema,
|
||||
moduleDisplayEntrypointSchema,
|
||||
packageRelativePathSchema,
|
||||
} from "@ekklesia/contracts";
|
||||
import { build, type Plugin } from "esbuild";
|
||||
|
||||
/**
|
||||
@@ -13,6 +18,14 @@ import { build, type Plugin } from "esbuild";
|
||||
*/
|
||||
export const MODULE_UI_SOURCE_ENTRYPOINT = "src/ui/index.tsx";
|
||||
export const MODULE_DISPLAY_SOURCE_ENTRYPOINT = "src/display/index.tsx";
|
||||
/** Where a declared browser contribution's source lives: `src/contributions/<local-name>/index.tsx`,
|
||||
* where the local name is the part of the contribution id after the module's own id. Derived rather
|
||||
* than configured, exactly like the two role entrypoints, so an author points the build nowhere. */
|
||||
export const MODULE_CONTRIBUTION_SOURCE_DIRECTORY = "src/contributions";
|
||||
|
||||
export function moduleContributionSourceEntrypoint(contributionId: string): string {
|
||||
return `${MODULE_CONTRIBUTION_SOURCE_DIRECTORY}/${contributionLocalName(contributionId)}/index.tsx`;
|
||||
}
|
||||
export const MODULE_MANIFEST_FILENAME = "ekklesia.module.json";
|
||||
|
||||
/** Matches `browser.json`'s `target`, so what TypeScript typechecks and what esbuild emits agree. */
|
||||
@@ -27,7 +40,7 @@ export type ModuleUiBuildErrorCode =
|
||||
| "MODULE_UI_STYLESHEET_UNDECLARED"
|
||||
| "MODULE_UI_BUILD_FAILED";
|
||||
|
||||
export type ModuleUiArtifactKind = "ui" | "display";
|
||||
export type ModuleUiArtifactKind = "ui" | "display" | "contribution";
|
||||
|
||||
const errorMessages: Readonly<Record<ModuleUiBuildErrorCode, string>> = Object.freeze({
|
||||
MODULE_UI_MANIFEST_UNREADABLE: `${MODULE_MANIFEST_FILENAME} could not be read or parsed.`,
|
||||
@@ -165,13 +178,17 @@ export interface BuildModuleUiOptions {
|
||||
}
|
||||
|
||||
export interface ModuleUiBuildResult {
|
||||
/** Built artifacts in stable role order: primary UI first, then display. Empty for backend-only
|
||||
* modules, which makes the canonical command usable unchanged by every module package. */
|
||||
/** Built artifacts in stable role order: primary UI, then display, then each declared contribution
|
||||
* in manifest order. Empty for backend-only modules, which makes the canonical command usable
|
||||
* unchanged by every module package. */
|
||||
readonly artifacts: readonly ModuleUiBuildArtifactResult[];
|
||||
}
|
||||
|
||||
export interface ModuleUiBuildArtifactResult {
|
||||
readonly kind: ModuleUiArtifactKind;
|
||||
/** For a contribution, the declared contribution id — so a multi-contribution build reports which
|
||||
* artifact it produced. Absent for the two role entrypoints. */
|
||||
readonly contributionId?: string;
|
||||
/** Absolute path of the artifact actually written, exactly as the manifest declares. */
|
||||
readonly outputFile: string;
|
||||
/** Absolute path of the fixed source entrypoint that produced it. */
|
||||
@@ -203,7 +220,15 @@ async function resolveDeclaredArtifacts(
|
||||
}
|
||||
|
||||
const display = entrypoints.display;
|
||||
const manifestContributions = isRecord(manifest) ? manifest.contributions : undefined;
|
||||
const declaredContributions = Array.isArray(manifestContributions) ? manifestContributions : [];
|
||||
for (const contribution of declaredContributions) {
|
||||
if (!moduleContributionDeclarationSchema.safeParse(contribution).success) {
|
||||
throw new ModuleUiBuildError("MODULE_UI_MANIFEST_UNREADABLE", "contribution");
|
||||
}
|
||||
}
|
||||
const declarations: readonly {
|
||||
readonly contributionId?: string;
|
||||
readonly declared: unknown;
|
||||
readonly kind: ModuleUiArtifactKind;
|
||||
readonly present: boolean;
|
||||
@@ -221,6 +246,13 @@ async function resolveDeclaredArtifacts(
|
||||
present: display !== undefined,
|
||||
source: MODULE_DISPLAY_SOURCE_ENTRYPOINT,
|
||||
},
|
||||
...(declaredContributions as { artifact: string; id: string }[]).map((contribution) => ({
|
||||
contributionId: contribution.id,
|
||||
declared: contribution.artifact,
|
||||
kind: "contribution" as const,
|
||||
present: true,
|
||||
source: moduleContributionSourceEntrypoint(contribution.id),
|
||||
})),
|
||||
];
|
||||
const artifacts: DeclaredModuleUiArtifact[] = [];
|
||||
|
||||
@@ -239,6 +271,9 @@ async function resolveDeclaredArtifacts(
|
||||
throw new ModuleUiBuildError("MODULE_UI_ENTRYPOINT_UNSAFE", declaration.kind);
|
||||
}
|
||||
artifacts.push({
|
||||
...(declaration.contributionId === undefined
|
||||
? {}
|
||||
: { contributionId: declaration.contributionId }),
|
||||
kind: declaration.kind,
|
||||
outputFile: path.resolve(moduleDirectory, declared),
|
||||
sourceFile: path.join(moduleDirectory, declaration.source),
|
||||
@@ -249,17 +284,24 @@ async function resolveDeclaredArtifacts(
|
||||
throw new ModuleUiBuildError("MODULE_UI_MANIFEST_UNREADABLE", "display");
|
||||
}
|
||||
|
||||
const displayArtifact = artifacts.find((artifact) => artifact.kind === "display");
|
||||
if (displayArtifact !== undefined) {
|
||||
for (const entrypointName of ["server", "schema", "migrations", "jobs", "ui"] as const) {
|
||||
const configured = entrypoints[entrypointName];
|
||||
if (
|
||||
typeof configured === "string" &&
|
||||
path.resolve(moduleDirectory, configured) === displayArtifact.outputFile
|
||||
) {
|
||||
throw new ModuleUiBuildError("MODULE_UI_ENTRYPOINT_COLLISION", "display");
|
||||
}
|
||||
// No declared artifact may overwrite another declared file — an entrypoint this build does not
|
||||
// produce (`server`, `schema`, ...), or another artifact it does. Checked before esbuild runs, so
|
||||
// a collision can never destroy output that was already correct.
|
||||
const backendEntrypointPaths = new Set(
|
||||
(["server", "schema", "migrations", "jobs"] as const)
|
||||
.map((entrypointName) => entrypoints[entrypointName])
|
||||
.filter((configured): configured is string => typeof configured === "string")
|
||||
.map((configured) => path.resolve(moduleDirectory, configured)),
|
||||
);
|
||||
const claimedOutputs = new Set<string>();
|
||||
for (const artifact of artifacts) {
|
||||
if (
|
||||
backendEntrypointPaths.has(artifact.outputFile) ||
|
||||
claimedOutputs.has(artifact.outputFile)
|
||||
) {
|
||||
throw new ModuleUiBuildError("MODULE_UI_ENTRYPOINT_COLLISION", artifact.kind);
|
||||
}
|
||||
claimedOutputs.add(artifact.outputFile);
|
||||
}
|
||||
|
||||
// Complete preflight before esbuild starts: a missing second source must not leave the first role's
|
||||
|
||||
@@ -26,7 +26,7 @@ async function main(): Promise<number> {
|
||||
}
|
||||
for (const artifact of result.artifacts) {
|
||||
process.stdout.write(
|
||||
`Built module UI (${artifact.kind}): ${path.relative(moduleDirectory, artifact.outputFile)}\n`,
|
||||
`Built module UI (${artifact.contributionId ?? artifact.kind}): ${path.relative(moduleDirectory, artifact.outputFile)}\n`,
|
||||
);
|
||||
}
|
||||
return 0;
|
||||
|
||||
@@ -34,7 +34,7 @@ async function createModule(options: ModuleFixtureOptions = {}): Promise<string>
|
||||
const manifest =
|
||||
options.manifest ??
|
||||
JSON.stringify({
|
||||
manifestVersion: 6,
|
||||
manifestVersion: 7,
|
||||
id: "example",
|
||||
name: "Example",
|
||||
version: "0.1.0",
|
||||
|
||||
Reference in New Issue
Block a user