Publishes one package release train to the Gitea npm registry under
River_of_Glory_Church, whose packages are publicly readable on purpose:
exactly the .tgz files the package-release gate proved, and nothing else.
Nothing is published by this change.

- scripts/publish-package-train.ts validates the whole local train before
  any request (gate manifest hash, version, revision, unmodified source,
  the nine packages, every artifact's size, SHA-256, integrity,
  SHA256SUMS line, and inner package.json), then publishes in dependency
  order with `npm publish <file.tgz>` under a staging tag. Each package
  is reconciled first (absent: publish; same bytes: accept; other bytes:
  hard stop, version burned), then read back: metadata (name, version,
  integrity, dependency maps, normalized bin, tarball on the registry)
  and the tarball itself, byte for byte, also anonymously. `latest` moves
  only after all nine verify; reruns converge and never delete anything.
  It writes a publication record. The token comes from
  EKKLESIA_PACKAGES_PUBLISH_TOKEN only, through a temporary npm config
  that refers to the variable.
- scripts/test-package-publication.sh proves it against a disposable
  Gitea 1.27.2 with public owners, a publisher team and an outsider:
  anonymous reads, refused unauthorized publishing, byte-identical round
  trips, the registry's own 409, partial-train recovery, the burned
  version hard stop, and dist-tag retry convergence.
- CI: package-release keeps its proven release and hands it on as an
  artifact with its manifest hash; the new package-publication job
  publishes exactly that artifact to the disposable Gitea. Artifact
  actions v3 (node20): v4 refuses any server other than github.com.
- .github/workflows/publish-packages.yml publishes to the real registry
  only by manual dispatch on main, after its own gate run, with the
  secret in the publish step alone.
- docs: the public-read model, the workflow, the record, credentials,
  immutability policy, provider moves, and the first-publication steps.

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

2026-10-08 09:49:27 -05:00

6.0 KiB

Raw Permalink Blame History

CLAUDE.md

Guidance for Claude Code (and other coding agents) working in this repository. This file is intentionally short and durable — it points at authoritative sources instead of restating their contents, because restated details drift.

What this repository is

Ekklesia is a modular, self-hosted church platform built as a strictly layered pnpm/TypeScript monorepo:

Core (core/) owns platform infrastructure: identity, database connectivity, migration execution, module discovery/lifecycle, and other feature-agnostic services. Core never imports a feature module, a surface, or an app.
Modules (modules/*, template at templates/module) are independently versioned product packages. They own their own data and migrations, declare capabilities/permissions through @ekklesia/contracts and @ekklesia/module-sdk, and must never import Core, another module, or a surface directly. Per ADR 0021 a module owns its UI; manifest v7 permits independently optional primary and full-viewport display artifacts, authored in React against the same role-neutral @ekklesia/module-ui-sdk ABI. Ekklesia mounts each through a separate surface role, while pnpm boundaries still rejects every non-React UI framework and non-.tsx presentation source.
Surfaces (surfaces/*) own the containing application shell, navigation, and every presentation concern a module does not. They consume public API/client contracts only, never Core or module internals directly.

These boundaries are enforced by pnpm boundaries (scripts/check-boundaries.ts), not just documented. Read docs/architecture/repository-boundaries.md and docs/architecture/platform-architecture.md before proposing any change that crosses a layer.

ADRs are authoritative

docs/architecture/decisions/ records durable architectural decisions. Accepted ADRs are immutable except for status and cross-reference corrections — do not edit their content to fit a new change. A changed decision gets a new ADR that supersedes the old one. Read the full ADR index (docs/architecture/decisions/README.md) and every ADR relevant to the area you are touching before designing a change; do not assume this file's summary of any decision is complete or current.

Read before you design

At minimum, read the current versions of:

docs/architecture/decisions/README.md and every ADR relevant to your change
docs/architecture/platform-architecture.md and docs/architecture/repository-boundaries.md
README.md (current platform status — what is and is not implemented)
docs/development/repository-workflow.md and docs/development/testing.md
CONTRIBUTING.md

These files change as the platform evolves. Inspect the actual current repository state (source, tests, package.json scripts, CI workflow) before relying on anything in this file or in your own memory of a prior session — treat stale assumptions as a bug to catch, not a shortcut.

Working conventions

Work on a clean branch off an up-to-date main; never commit or push directly to main; never change branch-protection settings.
Keep PRs focused on one bounded slice. Record major architectural changes in an ADR rather than burying them in an implementation.
Add or update tests when you change a contract or architectural rule. New behavior needs new test coverage, not just a passing existing suite.
Errors that reach a user, log, CLI, or pnpm doctor output must be sanitized: never expose secrets, connection strings, raw SQL, raw driver/exception messages, stack traces, causes, or machine-specific paths. Match the sanitization pattern already used by core/src/migrations/runner.ts and core/src/diagnostics/doctor.ts rather than inventing a new one.
Never run a database migration automatically (on import, on startup, in a test that isn't explicitly a migration test, or as a side effect of an unrelated command). Migrations are always an explicit, operator-invoked action.

Canonical verification commands

Run from the repository root; package.json is the source of truth if this list and the file ever disagree:

pnpm verify — the full code-only gate (format, lint, boundaries, typecheck, tests, module and migration validation, identity schema drift check, build). Docker-free; never touches a live database.
pnpm test:migrations:integration — live, disposable-PostgreSQL evidence: migration discovery, planning, and execution, plus the apps/api HTTP transport (signup, sign-in, principal resolution, sign-out). Requires Docker. Run this for any change touching either area.
pnpm test:package-release — builds the public @ekklesia/* package train, proves it reproducible, and proves a standalone module consumes exactly those tarballs. Publishes nothing. Run it for any change to the public packages or their release tooling.
pnpm test:package-publication — publishes a release train to a disposable Gitea (Docker) and proves the publication tool. Never the real registry. The real publication is the manual Publish packages workflow only; never run scripts/publish-package-train.ts against the real registry without the user's explicit intent.
pnpm doctor — read-only local readiness report. Never treat it as a substitute for pnpm verify or the integration suite.
pnpm migrations:plan / pnpm migrations:apply — read-only planning vs. mutating execution against DATABASE_URL. Never run migrations:apply without the user's explicit intent.
pnpm api:start — starts the identity HTTP transport against an already-migrated DATABASE_URL. It never applies migrations itself. Never run it without the user's explicit intent.

When you're unsure

If a task would require weakening an existing ADR's guarantee, introducing a second mechanism where one already exists (a second migration runner, a second discovery path, a second config system), or exposing something the boundary checker currently blocks, stop and surface the conflict instead of working around it.

6.0 KiB Raw Permalink Blame History