feat: add display kiosk host

2026-08-23 20:50:56 -05:00
parent be5ed7853d
commit 2e0fe059c3
80 changed files with 4868 additions and 397 deletions
@@ -1,17 +1,18 @@
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { packageRelativePathSchema } from "@ekklesia/contracts";
+import { moduleDisplayEntrypointSchema, packageRelativePathSchema } from "@ekklesia/contracts";
 import { build, type Plugin } from "esbuild";

 /**
- * The one supported way to turn a module's React/TSX UI source into the compiled browser artifact
- * its manifest declares as `entrypoints.ui` (ADR 0021, ADR 0022, ADR 0023).
+ * The one supported way to turn a module's React/TSX UI sources into the compiled browser artifacts
+ * its manifest declares as `entrypoints.ui` and `entrypoints.display`.
 *
 * Module authors do not write bundler configuration. They put their UI at
- * {@link MODULE_UI_SOURCE_ENTRYPOINT}, declare `entrypoints.ui` in their manifest, and run the
+ * the fixed role-specific source locations below, declare either or both artifacts, and run one
 * build; every option below is owned here so one decision applies to every module.
 */
 export const MODULE_UI_SOURCE_ENTRYPOINT = "src/ui/index.tsx";
+export const MODULE_DISPLAY_SOURCE_ENTRYPOINT = "src/display/index.tsx";
 export const MODULE_MANIFEST_FILENAME = "ekklesia.module.json";

 /** Matches `browser.json`'s `target`, so what TypeScript typechecks and what esbuild emits agree. */
@@ -19,17 +20,21 @@ export const MODULE_UI_BUILD_TARGET = "es2022";

 export type ModuleUiBuildErrorCode =
  | "MODULE_UI_MANIFEST_UNREADABLE"
-  | "MODULE_UI_ENTRYPOINT_NOT_DECLARED"
  | "MODULE_UI_ENTRYPOINT_UNSAFE"
+  | "MODULE_UI_ENTRYPOINT_COLLISION"
  | "MODULE_UI_SOURCE_MISSING"
  | "MODULE_UI_BUILD_FAILED";

+export type ModuleUiArtifactKind = "ui" | "display";
+
 const errorMessages: Readonly<Record<ModuleUiBuildErrorCode, string>> = Object.freeze({
  MODULE_UI_MANIFEST_UNREADABLE: `${MODULE_MANIFEST_FILENAME} could not be read or parsed.`,
-  MODULE_UI_ENTRYPOINT_NOT_DECLARED: `${MODULE_MANIFEST_FILENAME} declares no entrypoints.ui, so there is no module UI to build.`,
-  MODULE_UI_ENTRYPOINT_UNSAFE: `entrypoints.ui must be a package-relative path to a compiled .js or .mjs artifact inside the module.`,
-  MODULE_UI_SOURCE_MISSING: `Module UI source was not found at ${MODULE_UI_SOURCE_ENTRYPOINT}.`,
-  MODULE_UI_BUILD_FAILED: "The module UI bundle could not be produced.",
+  MODULE_UI_ENTRYPOINT_UNSAFE:
+    "A module UI entrypoint must be a package-relative path to a compiled .js or .mjs artifact inside the module.",
+  MODULE_UI_ENTRYPOINT_COLLISION:
+    "A display UI entrypoint must not overwrite another declared artifact.",
+  MODULE_UI_SOURCE_MISSING: "A declared module UI source entrypoint was not found.",
+  MODULE_UI_BUILD_FAILED: "A module UI bundle could not be produced.",
 });

 /** Carries a stable code and a fixed message. esbuild's own diagnostics are printed to stderr by
@@ -37,11 +42,17 @@ const errorMessages: Readonly<Record<ModuleUiBuildErrorCode, string>> = Object.f
 * other Ekklesia error boundary. */
 export class ModuleUiBuildError extends Error {
  readonly code: ModuleUiBuildErrorCode;
+  /** Safe role vocabulary that lets a developer identify which declared artifact failed without
+   * exposing a filesystem path or raw manifest value. */
+  readonly kind?: ModuleUiArtifactKind;

-  constructor(code: ModuleUiBuildErrorCode) {
+  constructor(code: ModuleUiBuildErrorCode, kind?: ModuleUiArtifactKind) {
    super(errorMessages[code]);
    this.name = "ModuleUiBuildError";
    this.code = code;
+    if (kind !== undefined) {
+      this.kind = kind;
+    }
    this.stack = `${this.name}: ${this.message}`;
  }
 }
@@ -83,9 +94,16 @@ export interface BuildModuleUiOptions {
 }

 export interface ModuleUiBuildResult {
-  /** Absolute path of the artifact actually written, which is exactly what the manifest declares. */
+  /** 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. */
+  readonly artifacts: readonly ModuleUiBuildArtifactResult[];
+}
+
+export interface ModuleUiBuildArtifactResult {
+  readonly kind: ModuleUiArtifactKind;
+  /** Absolute path of the artifact actually written, exactly as the manifest declares. */
  readonly outputFile: string;
-  /** Absolute path of the source entrypoint that produced it. */
+  /** Absolute path of the fixed source entrypoint that produced it. */
  readonly sourceFile: string;
 }

@@ -93,9 +111,12 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
 }

-/** The declared artifact path, validated the same way module discovery validates it, so the build
- * can never write somewhere discovery would later reject. */
-async function resolveDeclaredArtifact(moduleDirectory: string): Promise<string> {
+type DeclaredModuleUiArtifact = ModuleUiBuildArtifactResult;
+
+/** Reads the inert manifest and returns every declared UI artifact in deterministic role order. */
+async function resolveDeclaredArtifacts(
+  moduleDirectory: string,
+): Promise<readonly DeclaredModuleUiArtifact[]> {
  let manifest: unknown;
  try {
    manifest = JSON.parse(
@@ -106,20 +127,81 @@ async function resolveDeclaredArtifact(moduleDirectory: string): Promise<string>
  }

  const entrypoints = isRecord(manifest) ? manifest.entrypoints : undefined;
-  const declared = isRecord(entrypoints) ? entrypoints.ui : undefined;
-  if (declared === undefined) {
-    throw new ModuleUiBuildError("MODULE_UI_ENTRYPOINT_NOT_DECLARED");
+  if (!isRecord(entrypoints)) {
+    throw new ModuleUiBuildError("MODULE_UI_MANIFEST_UNREADABLE");
  }
-  // The path grammar is Core's, not this tool's: reusing the contracts schema means the build can
-  // never write to a location module discovery would later reject, even if that grammar changes.
-  if (
-    !packageRelativePathSchema.safeParse(declared).success ||
-    typeof declared !== "string" ||
-    ![".js", ".mjs"].includes(path.extname(declared).toLowerCase())
-  ) {
-    throw new ModuleUiBuildError("MODULE_UI_ENTRYPOINT_UNSAFE");
+
+  const display = entrypoints.display;
+  const declarations: readonly {
+    readonly declared: unknown;
+    readonly kind: ModuleUiArtifactKind;
+    readonly present: boolean;
+    readonly source: string;
+  }[] = [
+    {
+      declared: entrypoints.ui,
+      kind: "ui",
+      present: entrypoints.ui !== undefined,
+      source: MODULE_UI_SOURCE_ENTRYPOINT,
+    },
+    {
+      declared: isRecord(display) ? display.artifact : display,
+      kind: "display",
+      present: display !== undefined,
+      source: MODULE_DISPLAY_SOURCE_ENTRYPOINT,
+    },
+  ];
+  const artifacts: DeclaredModuleUiArtifact[] = [];
+
+  for (const declaration of declarations) {
+    if (!declaration.present) {
+      continue;
+    }
+    const declared = declaration.declared;
+    // The path grammar is Core's, not this tool's: reusing the contracts schema means the build can
+    // never write somewhere discovery would later reject, even if that grammar changes.
+    if (
+      typeof declared !== "string" ||
+      !packageRelativePathSchema.safeParse(declared).success ||
+      ![".js", ".mjs"].includes(path.extname(declared).toLowerCase())
+    ) {
+      throw new ModuleUiBuildError("MODULE_UI_ENTRYPOINT_UNSAFE", declaration.kind);
+    }
+    artifacts.push({
+      kind: declaration.kind,
+      outputFile: path.resolve(moduleDirectory, declared),
+      sourceFile: path.join(moduleDirectory, declaration.source),
+    });
  }
-  return path.resolve(moduleDirectory, declared);
+
+  if (display !== undefined && !moduleDisplayEntrypointSchema.safeParse(display).success) {
+    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");
+      }
+    }
+  }
+
+  // Complete preflight before esbuild starts: a missing second source must not leave the first role's
+  // output looking like a successful package build.
+  for (const artifact of artifacts) {
+    try {
+      await readFile(artifact.sourceFile);
+    } catch {
+      throw new ModuleUiBuildError("MODULE_UI_SOURCE_MISSING", artifact.kind);
+    }
+  }
+
+  return artifacts;
 }

 /**
@@ -130,52 +212,70 @@ async function resolveDeclaredArtifact(moduleDirectory: string): Promise<string>
 */
 export async function buildModuleUi(options: BuildModuleUiOptions): Promise<ModuleUiBuildResult> {
  const moduleDirectory = path.resolve(options.moduleDirectory);
-  const outputFile = await resolveDeclaredArtifact(moduleDirectory);
-  const sourceFile = path.join(moduleDirectory, MODULE_UI_SOURCE_ENTRYPOINT);
+  const artifacts = await resolveDeclaredArtifacts(moduleDirectory);
+  const pendingWrites: Array<readonly { path: string; contents: Uint8Array }[]> = [];

-  try {
-    await readFile(sourceFile);
-  } catch {
-    throw new ModuleUiBuildError("MODULE_UI_SOURCE_MISSING");
-  }
-
-  try {
-    await build({
-      absWorkingDir: moduleDirectory,
-      // Every dependency, React included, is bundled. The artifact must run in any host, including
-      // one that uses no React at all, so nothing is externalized (ADR 0023).
-      bundle: true,
-      define: {
-        // React reads this at module scope. Without it the bundle would reference `process`, a
-        // Node global that does not exist in a browser, and crash on load.
-        "process.env.NODE_ENV": '"production"',
-      },
-      entryPoints: [sourceFile],
-      // ESM only: the artifact is imported by a host with a dynamic `import()`, and the contract
-      // requires a real default export.
-      format: "esm",
-      jsx: "automatic",
-      // Unminified deliberately: an operator is expected to review the artifact they install
-      // (see docs/development/security.md), and nothing else in this repository minifies.
-      minify: false,
-      outfile: outputFile,
-      platform: "browser",
-      plugins: [rejectStylesheetImports()],
-      sourcemap: true,
-      target: MODULE_UI_BUILD_TARGET,
-      // Fail rather than silently shipping a partial bundle.
-      logLevel: "silent",
-    });
-  } catch (error) {
-    // esbuild's structured diagnostics are surfaced by the CLI; rethrow a sanitized error so a
-    // programmatic caller never receives raw paths or internals.
-    if (isRecord(error) && Array.isArray(error.errors)) {
-      throw Object.assign(new ModuleUiBuildError("MODULE_UI_BUILD_FAILED"), {
-        diagnostics: error.errors,
+  for (const artifact of artifacts) {
+    try {
+      const result = await build({
+        absWorkingDir: moduleDirectory,
+        // Every dependency, React included, is bundled. The artifact must run in any host, including
+        // one that uses no React at all, so nothing is externalized (ADR 0023).
+        bundle: true,
+        define: {
+          // React reads this at module scope. Without it the bundle would reference `process`, a
+          // Node global that does not exist in a browser, and crash on load.
+          "process.env.NODE_ENV": '"production"',
+        },
+        entryPoints: [artifact.sourceFile],
+        // ESM only: the artifact is imported by a host with a dynamic `import()`, and the contract
+        // requires a real default export.
+        format: "esm",
+        jsx: "automatic",
+        // Unminified deliberately: an operator is expected to review the artifact they install
+        // (see docs/development/security.md), and nothing else in this repository minifies.
+        minify: false,
+        outfile: artifact.outputFile,
+        platform: "browser",
+        plugins: [rejectStylesheetImports()],
+        sourcemap: true,
+        target: MODULE_UI_BUILD_TARGET,
+        // Fail rather than silently shipping a partial bundle.
+        logLevel: "silent",
+        // Compile every role successfully before writing any role. This makes a two-artifact build
+        // atomic with respect to parse/resolve/bundle failures rather than leaving a stale partial set.
+        write: false,
      });
+      pendingWrites.push(
+        result.outputFiles.map((outputFile) => ({
+          contents: outputFile.contents,
+          path: outputFile.path,
+        })),
+      );
+    } catch (error) {
+      // esbuild's structured diagnostics are surfaced by the CLI; rethrow a sanitized error so a
+      // programmatic caller never receives raw paths or internals.
+      if (isRecord(error) && Array.isArray(error.errors)) {
+        throw Object.assign(new ModuleUiBuildError("MODULE_UI_BUILD_FAILED", artifact.kind), {
+          diagnostics: error.errors,
+        });
+      }
+      throw new ModuleUiBuildError("MODULE_UI_BUILD_FAILED", artifact.kind);
    }
-    throw new ModuleUiBuildError("MODULE_UI_BUILD_FAILED");
  }

-  return { outputFile, sourceFile };
+  for (const [index, outputs] of pendingWrites.entries()) {
+    try {
+      for (const output of outputs) {
+        await mkdir(path.dirname(output.path), { recursive: true });
+        await writeFile(output.path, output.contents);
+      }
+    } catch {
+      throw new ModuleUiBuildError("MODULE_UI_BUILD_FAILED", artifacts[index]?.kind);
+    }
+  }
+
+  return Object.freeze({
+    artifacts: Object.freeze(artifacts.map((artifact) => Object.freeze({ ...artifact }))),
+  });
 }