feat: standalone module-build readiness for the public @ekklesia packages (ADR 0053)

Makes the public module-development package set usable from a module
repository outside the monorepo. Nothing is published.

- Curated @ekklesia/module-sdk: an explicit author API, no contracts
  barrel, no identity/authorization internals, no Drizzle and no legacy
  ModuleDatabase type. defineModuleRuntime returns the SDK's own named
  interfaces so a module's emitted declarations never reach into
  @ekklesia/contracts. defineModuleSchema is gone; createModuleTable and
  defineModuleSchemaMetadata live in @ekklesia/module-database.
- Drizzle: no longer a dependency of module-sdk or contracts. Core keeps
  the legacy Drizzle schema validator (moved to core/src/modules) and
  its legacy runtime support; drizzle-orm is an optional peer only.
- React is a peer (plus devDependency) of @ekklesia/ui; the boundary
  checker allows exactly that consumer-selected peer.
- @ekklesia/typescript-config is publishable; module-ui-host is private.
  Every public package carries "ekklesia.distribution":
  "module-development" and no monorepo-root prepack.
- module-pack reads the Node.js range from the module's own engines.node
  and recognizes Ekklesia packages by name plus that marker, so
  registry-installed packages are incorporated, SDK-compatibility
  checked, and never credited as third-party.
- scripts/pack-public-packages.ts (pnpm packages:pack) rebuilds, packs
  and inspects the nine public tarballs; scripts/test-standalone-module.sh
  (pnpm test:standalone-module, new CI job) installs them into a fixture
  module outside the repository and proves it typechecks, builds,
  packages, and verifies.
- Public-package boundary tests and module-development docs.

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

tests/public-packages.test.ts

@@ -0,0 +1,265 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import {
+  PUBLIC_PACKAGE_DISTRIBUTION,
+  PUBLIC_PACKAGES,
+  packedManifestProblems,
+  tarballFileProblems,
+} from "../scripts/pack-public-packages.js";
+
+/**
+ * The public module-development package boundary (ADR 0053): which packages may be published, what
+ * their manifests may say, and what the author-facing SDK exposes. The tarballs themselves are
+ * inspected by `pnpm packages:pack` and installed into a standalone module by
+ * `scripts/test-standalone-module.sh`.
+ */
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+type Manifest = Record<string, unknown> & {
+  name: string;
+  version: string;
+  private?: boolean;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  optionalDependencies?: Record<string, string>;
+  ekklesia?: Record<string, unknown>;
+  files?: string[];
+};
+
+async function readJson<T = Manifest>(file: string): Promise<T> {
+  return JSON.parse(await readFile(path.join(repositoryRoot, file), "utf8")) as T;
+}
+
+async function workspacePackages(): Promise<
+  Map<string, { directory: string; manifest: Manifest }>
+> {
+  const workspace = parse(await readFile(path.join(repositoryRoot, "pnpm-workspace.yaml"), "utf8"));
+  const packages = new Map<string, { directory: string; manifest: Manifest }>();
+  for (const pattern of workspace.packages as string[]) {
+    const directories = pattern.endsWith("/*")
+      ? (
+          await readdir(path.join(repositoryRoot, pattern.slice(0, -2)), {
+            withFileTypes: true,
+          }).catch(() => [])
+        )
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => `${pattern.slice(0, -2)}/${entry.name}`)
+      : [pattern];
+    for (const directory of directories) {
+      const manifest = await readJson(`${directory}/package.json`).catch(() => undefined);
+      if (manifest) packages.set(manifest.name, { directory, manifest });
+    }
+  }
+  return packages;
+}
+
+describe("the public package set", () => {
+  it("is exactly the packages that carry the distribution marker, and nothing else is publishable", async () => {
+    const packages = await workspacePackages();
+    const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
+    for (const entry of PUBLIC_PACKAGES) {
+      expect(packages.get(entry.name)?.directory, entry.name).toBe(entry.directory);
+    }
+    for (const [name, { manifest }] of packages) {
+      const marked = manifest.ekklesia?.distribution === PUBLIC_PACKAGE_DISTRIBUTION;
+      expect(marked, name).toBe(publicNames.has(name));
+      // Internal packages stay private, so no publish can ever take them by accident.
+      expect(manifest.private === true, name).toBe(!publicNames.has(name));
+    }
+    expect(packages.get("@ekklesia/core")?.manifest.private).toBe(true);
+    expect(packages.get("@ekklesia/module-ui-host")?.manifest.private).toBe(true);
+    expect(packages.get("@ekklesia/module-template")?.manifest.private).toBe(true);
+  });
+
+  it("uses one coordinated version, and depends only on other public packages through the workspace", async () => {
+    const platformVersion = (await readJson("package.json")).version;
+    const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
+    for (const entry of PUBLIC_PACKAGES) {
+      const manifest = await readJson(`${entry.directory}/package.json`);
+      expect(manifest.version, entry.name).toBe(platformVersion);
+      expect(manifest.license, entry.name).toBe("AGPL-3.0-or-later");
+      for (const field of ["dependencies", "peerDependencies", "optionalDependencies"] as const) {
+        for (const [name, range] of Object.entries(manifest[field] ?? {})) {
+          if (!name.startsWith("@ekklesia/")) continue;
+          expect(publicNames.has(name), `${entry.name} ${field} ${name}`).toBe(true);
+          // `pnpm pack` turns this into the exact coordinated version.
+          expect(range, `${entry.name} ${field} ${name}`).toBe("workspace:*");
+        }
+      }
+    }
+  });
+
+  it("runs no monorepo-root command, or any other script, when a consumer installs or packs it", async () => {
+    for (const entry of PUBLIC_PACKAGES) {
+      const manifest = await readJson(`${entry.directory}/package.json`);
+      for (const script of ["preinstall", "install", "postinstall", "prepare", "prepack"]) {
+        expect(manifest.scripts?.[script], `${entry.name} ${script}`).toBeUndefined();
+      }
+      expect(JSON.stringify(manifest.scripts ?? {}), entry.name).not.toContain("--workspace-root");
+    }
+  });
+
+  it("keeps module-pack's own LICENSE identical to the repository's", async () => {
+    // pnpm adds the workspace LICENSE to a tarball only when no packed path looks like a licence, and
+    // module-pack ships `licenses/` and `license-supplements/`, so it carries its own copy.
+    expect(await readFile(path.join(repositoryRoot, "packages/module-pack/LICENSE"))).toEqual(
+      await readFile(path.join(repositoryRoot, "LICENSE")),
+    );
+  });
+});
+
+describe("the curated Module SDK", () => {
+  async function sdkExports(): Promise<string[]> {
+    const source = await readFile(
+      path.join(repositoryRoot, "packages/module-sdk/src/index.ts"),
+      "utf8",
+    );
+    expect(source).not.toMatch(/export\s*\*/u);
+    const names: string[] = [];
+    for (const block of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/gu)) {
+      for (const item of (block[1] ?? "").split(",")) {
+        const name = item
+          .replace(/^\s*type\s+/u, "")
+          .split(/\s+as\s+/u)
+          .pop()
+          ?.trim();
+        if (name) names.push(name);
+      }
+    }
+    return names.sort();
+  }
+
+  it("exposes the author API only", async () => {
+    const names = await sdkExports();
+    expect(names).toContain("defineModuleRuntime");
+    expect(names).toContain("ModuleRouteHandlerContext");
+    expect(names).toContain("parseModuleManifest");
+    for (const name of names) {
+      // No identity or authorization internals, no Drizzle, and no legacy database facade.
+      expect(name).not.toMatch(
+        /Authoriz|Permission(?:Grant|Decision)|Identity|Session|Credential|Drizzle(?!MigrationJournal)|^ModuleDatabase$|^ModuleSchemaDefinition$|defineModuleSchema|createModuleTable|^parseEkklesia/u,
+      );
+    }
+  });
+
+  it("does not make Drizzle a dependency of a module that does not use it", async () => {
+    const sdk = await readJson("packages/module-sdk/package.json");
+    expect(Object.keys(sdk.dependencies ?? {})).toEqual(["@ekklesia/contracts"]);
+    expect(sdk.peerDependencies ?? {}).toEqual({});
+    // Everything the SDK installs: Drizzle is at most an optional peer, and no runtime path reaches it.
+    for (const name of ["contracts", "module-database"]) {
+      const manifest = await readJson(`packages/${name}/package.json`);
+      expect(manifest.dependencies?.["drizzle-orm"], name).toBeUndefined();
+      expect(manifest.optionalDependencies?.["drizzle-orm"], name).toBeUndefined();
+      if (manifest.peerDependencies?.["drizzle-orm"]) {
+        expect(manifest.peerDependenciesMeta?.["drizzle-orm"]?.optional, name).toBe(true);
+      }
+    }
+    const contractsSource = path.join(repositoryRoot, "packages/contracts/src");
+    for (const file of await readdir(contractsSource)) {
+      // Only types: Core alone validates the legacy Drizzle schema definition, with its own Drizzle.
+      const source = await readFile(path.join(contractsSource, file), "utf8");
+      for (const line of source.split("\n").filter((text) => /from\s+"drizzle-orm/u.test(text))) {
+        expect(line, file).toMatch(/^import type /u);
+      }
+    }
+    const contracts = await readJson("packages/contracts/package.json");
+    expect(Object.keys(contracts.exports as object)).toEqual([".", "./module-package"]);
+  });
+});
+
+describe("module authors' dependencies", () => {
+  it("never name @ekklesia/contracts directly", async () => {
+    const template = await readJson("templates/module/package.json");
+    const fixture = await readJson("tests/fixtures/standalone-module/package.json");
+    for (const manifest of [template, fixture]) {
+      expect(JSON.stringify(manifest), manifest.name).not.toContain("@ekklesia/contracts");
+    }
+    const guide = await readFile(
+      path.join(repositoryRoot, "docs/module-development/README.md"),
+      "utf8",
+    );
+    // Never shown as a dependency to add, and stated not to be one.
+    expect(guide).not.toMatch(/"@ekklesia\/contracts"\s*:/u);
+    expect(guide).toContain("`@ekklesia/contracts` is not a direct dependency.");
+  });
+
+  it("pin module-pack exactly and declare engines.node in the standalone fixture", async () => {
+    const fixture = await readJson("tests/fixtures/standalone-module/package.json");
+    const devDependencies = fixture.devDependencies as Record<string, string>;
+    expect(devDependencies["@ekklesia/module-pack"]).toMatch(/^\d+\.\d+\.\d+$/u);
+    expect((fixture.engines as Record<string, string>).node).toBeTruthy();
+  });
+});
+
+describe("@ekklesia/typescript-config", () => {
+  it("ships only its configurations, which extend each other by relative path", async () => {
+    const manifest = await readJson("packages/typescript-config/package.json");
+    expect(manifest.files?.every((file) => /^[a-z-]+\.json$/u.test(file))).toBe(true);
+    for (const file of manifest.files ?? []) {
+      const config = await readJson<{ extends?: string }>(`packages/typescript-config/${file}`);
+      if (config.extends !== undefined)
+        expect(config.extends, file).toMatch(/^\.\/[a-z-]+\.json$/u);
+    }
+  });
+});
+
+describe("the tarball inspection", () => {
+  const good = {
+    dependencies: { "@ekklesia/contracts": "0.1.2", zod: "4.4.3" },
+    devDependencies: { "@ekklesia/core": "0.1.2" },
+    ekklesia: { distribution: PUBLIC_PACKAGE_DISTRIBUTION, layer: "module-sdk" },
+    files: ["dist"],
+    license: "AGPL-3.0-or-later",
+    name: "@ekklesia/module-sdk",
+    scripts: { build: "tsc" },
+    version: "0.1.2",
+  };
+  const expected = { name: "@ekklesia/module-sdk", version: "0.1.2" };
+
+  it("accepts a packed manifest that names only the coordinated train", () => {
+    expect(packedManifestProblems(good, expected)).toEqual([]);
+  });
+
+  it("refuses workspace ranges, privacy, missing markers, lifecycle scripts, and mixed trains", () => {
+    const cases: Record<string, unknown>[] = [
+      { ...good, dependencies: { "@ekklesia/contracts": "workspace:*" } },
+      { ...good, private: true },
+      { ...good, ekklesia: { layer: "module-sdk" } },
+      { ...good, scripts: { prepack: "pnpm --workspace-root exec turbo run build" } },
+      { ...good, scripts: { postinstall: "node setup.js" } },
+      { ...good, dependencies: { "@ekklesia/contracts": "0.1.1" } },
+      { ...good, peerDependencies: { "@ekklesia/core": "0.1.2" } },
+      { ...good, version: "0.1.3" },
+    ];
+    for (const manifest of cases) {
+      expect(packedManifestProblems(manifest, expected), JSON.stringify(manifest)).not.toEqual([]);
+    }
+  });
+
+  it("accepts only declared built files with sources, the manifest, and a LICENSE", () => {
+    const hasSource = (file: string) => ["index", "http"].includes(file);
+    expect(
+      tarballFileProblems(
+        ["LICENSE", "package.json", "dist/index.js", "dist/index.d.ts", "dist/http.js.map"],
+        good,
+        hasSource,
+      ),
+    ).toEqual([]);
+    for (const files of [
+      ["package.json", "dist/index.js"],
+      ["LICENSE", "package.json", "dist/removed.js"],
+      ["LICENSE", "package.json", "src/index.ts"],
+      ["LICENSE", "package.json", "tsconfig.json"],
+      ["LICENSE", "package.json", "dist/index.test.js"],
+    ]) {
+      expect(tarballFileProblems(files, good, hasSource), files.join(" ")).not.toEqual([]);
+    }
+  });
+});