docs: propose ADR 0053, standalone module builds from Ekklesia packages over the npm registry protocol #78

Merged

Zayin_Admin merged 1 commits from docs/adr-0053-module-package-distribution into main 2026-10-08 02:10:19 +00:00

Conversation 1 Commits 1 Files Changed 2

+254

ekklesia-bot commented 2026-10-08 01:46:33 +00:00

Member

Copy Link

Copy Source

Proposes ADR 0053: A module builds outside the monorepo, from Ekklesia packages published over the npm registry protocol. Docs only.

It defines the external module-development and package-distribution contract that ADR 0049 deferred. Installing a module stays registry-free; the registry is only for building one.

Decisions

• Protocol, not provider. Packages are distributed over the standard npm registry protocol; Gitea may host the private phase.
  • Host-neutral lockfiles and an Ekklesia proxy are not required.
  • A registry move may need a one-time .npmrc change and a lockfile regeneration; integrity hashes keep verifying content.
• Public set.
  • Author API: module-sdk, module-database, module-ui-sdk, design-tokens.
  • Tooling: module-ui-build, module-pack, typescript-config.
  • ui as a pre-1.0 component API.
  • contracts only as a transitive implementation dependency.
  • core, the apps, module-ui-host and module-template are never published.
• Curated SDK before the first publication.
  • No full contracts barrel.
  • No forced Drizzle at the SDK root.
  • No legacy Drizzle database contract in the standalone surface; Core still serves the legacy facade for ADR 0050's deprecation window.
  • Drizzle support lives in the module-database adapter.
• Dependency rules.
  • React and ReactDOM are peers of the public UI packages. ADR 0023's bundling is unchanged; the peer only prevents two React copies in one module bundle.
  • Drizzle is an optional peer only where the adapter needs it.
  • Modules put runtime packages in dependencies and tooling and config in devDependencies.
• Versioning.
  • One coordinated 0.x version, equal to the platform version, with no mixed trains.
  • Ranges in source, exact artifacts in lockfiles; module-pack pinned exactly.
  • Independent versions are deferred.
• Standalone packaging.
  • No monorepo checkout.
  • The module declares its own Node.js range (engines.node).
  • The packager recognizes Ekklesia packages by identity and metadata, not by path.
  • No monorepo-root commands run at install time.
• Supply chain.
  • Versions are immutable, and frozen-lockfile integrity is part of reproducibility.
  • Release CI packs the public set, inspects the tarballs (intended contents, LICENSE, no workspace: ranges), installs them into a clean standalone module fixture, and proves build, package and verify before publishing.
  • Signing is deferred.
• Private phase. No committed secrets; credentials come from the environment. Actual read access must be verified before the first publication, so private packages never reach an anonymously readable registry by accident.
• Release train. Build → pack → standalone tarball smoke → publish immutable versions → downstream module CI.
• Signage. The goal is a normal standalone repository with versioned @ekklesia/* dependencies and its own lockfile; its CI never clones Ekklesia. The migration itself is a separate change.

Relationship to other ADRs

• Extends 0049: this is its deferred SDK-publishing step.
• Related: 0002, 0006, 0021, 0023, 0039, 0048, 0050, 0051, 0052.
• ADR 0047 is still Proposed and assembles modules into the platform workspace. It must be revised against this ADR before it is accepted.

Changes

• docs/architecture/decisions/0053-standalone-module-development-packages.md (new, Proposed)
• the ADR index entry

Verification

• pnpm verify passes.
• A relative-link and anchor check of the changed docs passes.

🤖 Generated with Claude Code

Proposes **ADR 0053: A module builds outside the monorepo, from Ekklesia packages published over the npm registry protocol**. Docs only. It defines the external module-development and package-distribution contract that ADR 0049 deferred. Installing a module stays registry-free; the registry is only for building one. ## Decisions - **Protocol, not provider.** Packages are distributed over the standard npm registry protocol; Gitea may host the private phase. - Host-neutral lockfiles and an Ekklesia proxy are **not** required. - A registry move may need a one-time `.npmrc` change and a lockfile regeneration; integrity hashes keep verifying content. - **Public set.** - Author API: `module-sdk`, `module-database`, `module-ui-sdk`, `design-tokens`. - Tooling: `module-ui-build`, `module-pack`, `typescript-config`. - `ui` as a pre-1.0 component API. - `contracts` only as a transitive implementation dependency. - `core`, the apps, `module-ui-host` and `module-template` are never published. - **Curated SDK before the first publication.** - No full contracts barrel. - No forced Drizzle at the SDK root. - No legacy Drizzle database contract in the standalone surface; Core still serves the legacy facade for ADR 0050's deprecation window. - Drizzle support lives in the `module-database` adapter. - **Dependency rules.** - React and ReactDOM are peers of the public UI packages. ADR 0023's bundling is unchanged; the peer only prevents two React copies in one module bundle. - Drizzle is an optional peer only where the adapter needs it. - Modules put runtime packages in `dependencies` and tooling and config in `devDependencies`. - **Versioning.** - One coordinated 0.x version, equal to the platform version, with no mixed trains. - Ranges in source, exact artifacts in lockfiles; `module-pack` pinned exactly. - Independent versions are deferred. - **Standalone packaging.** - No monorepo checkout. - The module declares its own Node.js range (`engines.node`). - The packager recognizes Ekklesia packages by identity and metadata, not by path. - No monorepo-root commands run at install time. - **Supply chain.** - Versions are immutable, and frozen-lockfile integrity is part of reproducibility. - Release CI packs the public set, inspects the tarballs (intended contents, `LICENSE`, no `workspace:` ranges), installs them into a clean standalone module fixture, and proves build, package and verify before publishing. - Signing is deferred. - **Private phase.** No committed secrets; credentials come from the environment. Actual read access must be verified before the first publication, so private packages never reach an anonymously readable registry by accident. - **Release train.** Build → pack → standalone tarball smoke → publish immutable versions → downstream module CI. - **Signage.** The goal is a normal standalone repository with versioned `@ekklesia/*` dependencies and its own lockfile; its CI never clones Ekklesia. The migration itself is a separate change. ## Relationship to other ADRs - **Extends 0049:** this is its deferred SDK-publishing step. - **Related:** 0002, 0006, 0021, 0023, 0039, 0048, 0050, 0051, 0052. - **ADR 0047** is still Proposed and assembles modules into the platform workspace. It must be revised against this ADR before it is accepted. ## Changes - `docs/architecture/decisions/0053-standalone-module-development-packages.md` (new, Proposed) - the ADR index entry ## Verification - `pnpm verify` passes. - A relative-link and anchor check of the changed docs passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

ekklesia-bot added 1 commit 2026-10-08 01:46:34 +00:00

docs: propose ADR 0053, standalone module builds from Ekklesia packages over the npm registry protocol ... 47e64c6f39

Defines the external module-development and package-distribution contract
that ADR 0049 deferred.

- Protocol, not provider: packages are distributed over the standard npm
  registry protocol. Gitea may host the private phase. Host-neutral
  lockfiles and an Ekklesia proxy are not required; a registry move may need
  one configuration change and a lockfile regeneration, while integrity hashes
  keep verifying content.
- Public set:
  - Author API: module-sdk, module-database, module-ui-sdk, design-tokens.
  - Tooling: module-ui-build, module-pack, typescript-config.
  - ui as a pre-1.0 component API.
  - contracts only as a transitive implementation dependency.
  - Core, apps, module-ui-host, and module-template stay unpublished.
- Curated SDK before first publication: no full contracts barrel, no forced
  Drizzle at the SDK root, and no legacy Drizzle database contract in the
  standalone surface. Drizzle support lives in module-database's adapter.
- Dependency rules: React/ReactDOM are peers of the public UI packages
  (bundling per ADR 0023 is unchanged); Drizzle is an optional peer only
  where the adapter needs it; modules put runtime packages in dependencies
  and tooling/config in devDependencies.
- Versioning: one coordinated 0.x release version equal to the platform
  version, with no mixed trains. Ranges go in source and exact artifacts in
  lockfiles; module-pack is pinned exactly; independent versions deferred.
- Standalone packaging: no monorepo checkout. The module declares its own
  Node range (engines.node). The packager recognizes Ekklesia packages by
  identity and metadata, not path. No monorepo-root commands at install time.
- Supply chain: immutable versions, frozen-lockfile integrity, and a
  pre-publication smoke that installs the packed tarballs into a clean
  standalone fixture and proves build, package, and verify. Signing deferred.
- Private phase: no committed secrets; credentials come from the
  environment; verify actual read access before the first publication.

Status Proposed. ADR 0047 (still proposed) must be revised against this. No
code, registry, credential, or Signage changes.

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

Zayin_Admin approved these changes 2026-10-08 02:10:14 +00:00

Zayin_Admin merged commit 9426c83109 into main 2026-10-08 02:10:19 +00:00

Zayin_Admin deleted branch docs/adr-0053-module-package-distribution 2026-10-08 02:10:19 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Zayin_Admin

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

Joey Zayin_Admin ekklesia-bot

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Zayin/Ekklesia#78