31 Commits

Include renames

Author	SHA1	Message	Date
ekklesiaandClaude Opus 5.5	aaa7ebfd84	fix: keep Drizzle out of every published declaration (ADR 0053) ... @ekklesia/contracts still emitted a type-only import of drizzle-orm/node-postgres for the legacy ModuleDatabase facade, so a standalone module type-checked only because skipLibCheck hid it. - ModuleDatabase, LegacyModuleRuntimeServices and AnyModuleRuntimeServices move to core/src/modules/database.ts, beside the facade Core builds; the facade itself is unchanged. - contracts' runtime, route, and services generics no longer name an ORM: the database type is a plain parameter defaulting to the ABI v1 executor, and the legacy definition's database is opaque until Core specializes it. Core and apps/api name the legacy types from Core. - contracts drops its drizzle-orm optional peer and devDependency; Drizzle stays public only through @ekklesia/module-database/drizzle. - The facade's type-level test moves from contracts to Core. - Regression proof: the standalone fixture type-checks with skipLibCheck: false against the packed tarballs, with no drizzle-orm installed (the smoke asserts both). Against the previous contracts tarball the same check fails with TS2307 on drizzle-orm/node-postgres. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 07:40:43 -05:00
ekklesiaandClaude Opus 5.5	89d5d0f2da	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]>	2026-10-08 07:28:54 -05:00
ekklesiaandClaude Opus 5.5	85fae9e07e	feat: Module Package v1 carries the module's own license (ADR 0051) ... Every Module Package v1 now declares the module's license and carries its text. packageFormat stays 1; pre-ADR-0051 metadata fails closed. - Contracts: ekklesia.package.json requires an SPDX `license` expression, validated with spdx-expression-parse, with UNLICENSED and non-expressions refused. The `files` list must hold exactly one non-empty root LICENSE. The package contracts move to the @ekklesia/contracts/module-package subpath, so the SPDX parser and its data (spdx-exceptions and spdx-license-ids ship no licence files) never reach a module bundle through the SDK's re-export of the contracts root. - Packager: reads the source package.json's string SPDX declaration and never invents one. It requires an explicit --license-file (a non-empty regular file, no symlink, no parent search, no download) and copies its bytes unchanged to LICENSE, listed with size and SHA-256 and covered by the archive digest. THIRD_PARTY_NOTICES stays third-party only, and bundled Ekklesia code stays in `incorporates`. - Verifier: rejects missing or invalid license metadata, and a missing, unlisted, duplicated, or corrupted LICENSE, through the schema and the existing strict inventory. - Template: packaged as AGPL-3.0-or-later with the repository's canonical LICENSE, passed explicitly (Dockerfile, smoke, docs). Packing it twice gives byte-identical archives. Started by Codex; reviewed and completed in Claude Code (empty license-text refusal, schema non-empty LICENSE, symlink and empty-file tests). ADR 0051 is Accepted. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 18:51:03 -05:00
ekklesia	859675c3c7	feat: add module database ABI v1 adapters	2026-10-07 16:44:28 -05:00
ekklesiaandClaude Opus 5.5	27d85e0162	fix(smoke): hand the verifier the package's archive and digest as one readable release pair ... The split deploy smoke failed in CI with "The SHA-256 file could not be read." BuildKit's local exporter creates its output directory (`--output type=local,dest=$work/module-package`) with mode 0700, owned by whoever ran the build. That directory was mounted into the verifier, which runs as the image's unprivileged `node` user (uid 1000). In CI the build runs as root, so the directory was root:root 0700 and the verifier could read neither file; the digest file is simply read first. On a workstation the build runs as uid 1000, the same uid as `node`, so it was readable by coincidence. scripts/lib/module-package-release.sh turns one build's output into the release pair: it requires exactly one archive and its .sha256 and nothing else, checks that the digest line names that archive, then creates a fresh directory that must not exist yet (0755) and copies both files into it (0644). The smoke stages and mounts only that directory; BuildKit's output directory is never mounted. Archive-digest verification stays mandatory: the verifier still reads the .sha256 file. Nothing in the verifier changed. Tests: the helper is driven in bash against a 0700 build output, and refuses a missing, malformed, or mismatched digest, stray output, a second archive, and an existing release directory, creating nothing. A static test pins the smoke to the release pair and the verifier's single mount with --sha256-file. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 13:10:58 -05:00
ekklesiaandClaude Opus 5.5	35ef31df9f	feat: Ekklesia Module Package v1, the canonical packager and verifier (ADR 0049) ... A separately versioned module is now distributed as one deterministic .tar.gz and its SHA-256, produced by an Ekklesia-owned packager and checked by Core before anything is installed. This slice implements the portable `any` target, with the module template as the end-to-end proof. ADR 0049 is accepted. @ekklesia/contracts: the Module Package v1 contract. The strict ekklesia.package.json schema (packageFormat 1, identity, target, runtime, provenance, incorporated Ekklesia packages, strict transitional facts, an exact byte-wise-sorted file list with size and SHA-256), target names, and the generated runtime package.json. @ekklesia/module-pack (new, tooling): `ekklesia-pack-module --module <dir> --target any --out <dir> --source-revision <commit>`. - Bundles server, schema, and jobs with esbuild, SDK, contracts, and Drizzle included; only Node built-ins remain imports. Any warning, unresolved import, external dependency, or native or platform-specific package fails. - Copies browser artifacts as built, after proving them current, and the migrations; generates package.json and ekklesia.package.json; never ships src, tests, declarations, source maps, or workspace ranges. - THIRD_PARTY_NOTICES: every third-party package traced from the bundles' own inputs, credited once with its declared licence and every licence, copying, copyright, and notice file it ships. A missing licence fails; a missing text fails unless its standard text is complete without copyright lines (Apache-2.0, vendored, needed by drizzle-orm). - Deterministic ustar and gzip: sorted paths, uid/gid 0, empty names, mtime 0, 0755/0644, no links. Byte-identical across runs and machines. - Writes only the archive and its .sha256; never deploys, links, or installs, so the workspace's install state is untouched. Core: verifyModulePackage and `verify-module-package.js <archive> [--sha256 | --sha256-file] [--extract-to <new dir>]`. Reads the archive in memory and refuses links, special entries, setuid/setgid/sticky modes, unsafe or escaping paths, and a second top-level directory; checks metadata, every file, identity, target, Node.js range, SDK, and the transitional Drizzle agreement; runs the platform's module and migration discovery; loads the backend once in a forked process with an empty environment; only then extracts, with normalized modes, into a new directory. Errors are sanitized. @ekklesia/module-ui-build: analyzeModuleUi reports each artifact's inputs and whether the built file is current. The nested stylesheet build now works from the module directory, so artifacts no longer depend on the caller's working directory. The split deploy smoke builds the package with the canonical packager (scripts/lib/build-module-package.Dockerfile replaces the test-only pnpm deploy packaging), verifies it with the same generic image, installs the verified tree, removes it, and reinstalls the exact same archive. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 12:44:54 -05:00
ekklesiaandClaude Opus 5.5	e36b70d8d4	feat: one generic image, with installed modules in installation-owned storage (ADR 0048) ... The production image now contains zero feature modules and is the same for every installation. Installed modules live in module storage that one Core resolver selects from EKKLESIA_MODULES_DIR: the checkout's modules/ when unset, an absolute path that must exist when set (/var/lib/ekklesia/modules in the image). A relative, blank, missing, or unreadable configured directory fails closed with a sanitized error that never contains the value. - Host configuration reads EKKLESIA_MODULES_DIR. The API, migration plan, apply and validate, module validation, module enablement, and Doctor all resolve it the same way; the test-only API override still takes precedence. - Doctor receives Core's migrations directory explicitly instead of deriving it from the modules directory's parent. - The migration runner retains and reports the applied history of a module that is not installed, and plans and applies Core's and present modules' migrations around it. Core's history and every installed module's history stay strict: a missing or changed applied migration, or a downgrade, still fails. No down migrations, no data deletion. - deploy/Dockerfile copies no module and installs nothing for the module template; .dockerignore excludes modules/ and the build refuses a context that contains it; the runtime has an empty root-owned /var/lib/ekklesia/modules and sets EKKLESIA_MODULES_DIR. - deploy/compose.yaml bind-mounts EKKLESIA_MODULES_HOST_DIR read-only into api and migrate, with create_host_path disabled. - scripts/check-image.sh proves the image holds no modules and that a populated modules/ directory leaves its runtime file system identical; CI runs it. - The split deploy smoke now uses the same generic image: it boots with no modules, installs a self-contained test module packaged from the template (test-only), migrates and restarts, removes it (Core runs, planning reports the retained history, data survives), and restores it with its data. Docs: deploy README (module storage, install/update/remove/restore, the runtime modules target), .env.example, API configuration, module development guide, testing, workflow, security, and the architecture overview. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 08:38:14 -05:00
ekklesiaandClaude Opus 5.5	0ec1755279	docs: the server runs Gitea 1.27.2, not 1.24.2; say what it actually honours ... The CI documentation, the workflow header, the README, ADR 0047 and the sweep's comment all said the server was Gitea 1.24.2, which ignores `permissions`, `concurrency` and `timeout-minutes`. The server reports 1.27.2 (GET /api/v1/version). Each claim is now stated from what is verified on this server: - `concurrency` is honoured, observed: Ekklesia runs 133 and 135 were cancelled when a newer run started for the same pull request; - `permissions` is supported by 1.27 with Gitea's own scopes, but the token's actual authority is not visible through the API and not yet proven, so nothing claims the job token is read-only; - `timeout-minutes` is no longer listed as unsupported, but is not verified, and teardown still relies on the stack sweep and a reaper. Requirement 1 for executing untrusted contributions (upgrade to the 1.26 line or later) is marked done; items 2 and 3, configuring and proving token authority, remain. ADR 0047 (still Proposed) restates its "docker run, not a reusable workflow" reasons for 1.27, where private sources are supported. The reasons still hold without the 1.24 argument. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-05 22:11:00 -05:00
ekklesiaandClaude Opus 5.5	62951975da	fix(ci): nothing a CI job starts outlives it, even when the runner kills the job ... A migration-smoke stack (PostgreSQL and SeaweedFS) ran on the shared runner for two days. Every CI script removes its stack in an EXIT trap, but a trap never runs when the runner kills the job container: a cancelled job, or the runner's own time limit (Gitea 1.24 ignores timeout-minutes). Reproduced: SIGKILL of the infrastructure smoke mid-run leaves exactly that stack running. Cleanup now has three layers: - the script's own trap, unchanged; - a final `if: always()` step in every job that starts stacks (infrastructure-smoke, migration-smoke, image-build, deploy-smoke) runs `scripts/ci-sweep.sh --job`, which removes everything that job started at any age; - a first step in each of those jobs runs `scripts/ci-sweep.sh --stale`, which removes CI stacks older than three hours: what a killed job left before it could clean up. How stacks are found is defined once, in scripts/lib/ci-project.sh: - every CI Compose project is named `ekklesia-ci-<run>-<attempt>-<job key>-<kind>-<unique>`, and Compose labels its containers, networks and volumes with that name; - the deploy smoke labels everything it starts outside Compose: browser, kiosk and driver containers, the kiosk volume, built images; - images also record when CI built them. An image's own creation time can be its base's (BuildKit, metadata-only builds), and the sweep removed a brand-new image as "old" until it stopped trusting that. The job key is per matrix leg, so one topology's cleanup cannot remove the other's running stack. The sweep never touches anything outside the ekklesia-ci- prefix, disconnects rather than removes a job container attached to a stack's network, and refuses --job outside CI. Network creation times are read as RFC 3339; Docker's default form was unparseable. scripts/test-ci-sweep.sh proves all of that against real Docker, and CI runs it before relying on it. security.md and testing.md document the rule, and that it complements, not replaces, a runner-side reaper. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-06 02:01:01 +00:00
ekklesiaandClaude Opus 5.5	703d92436b	test(ci): every CI stack is cleaned up, even when its job is killed ... A migration-smoke stack (PostgreSQL and SeaweedFS) leaked on the shared runner and ran for two days, until it was removed by hand. Every CI script already tears its stack down in an EXIT/INT/TERM trap, but a trap never runs when the runner kills the job container: a cancelled job, or the runner's own time limit, since Gitea 1.24 ignores timeout-minutes. Static checks (tests/ci-scripts.test.ts): - every stack script names its project through one helper: the reserved ekklesia-ci- prefix, run, attempt, job key, and a unique suffix; - everything the deploy smoke creates outside Compose carries the CI label; - every workflow job that starts stacks sweeps stale CI stacks first, and removes its own in a final if: always() step. Each matrix leg has its own key, so one cannot remove the other's running stack. Behaviour against real Docker (scripts/test-ci-sweep.sh): - --job removes this job's containers, network, volume, image and staging directory, and leaves other jobs' and non-CI stacks alone; - --job disconnects, never removes, a job container on the stack's network, and refuses to run outside CI; - --stale spares young stacks and removes old ones, never anything outside the prefix. Fails today: there is no helper, no sweep, no label and no step. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-06 02:01:01 +00:00
ekklesiaandClaude Opus 5.5	dcbd7613ee	test(deploy): load the same image twice over HTTP/2, and pin storage CORS ... Two checks on storage delivery through the proxy, in both topologies. The same signed image, twice, over a real HTTP/2 connection (node:http2; Node's fetch speaks HTTP/1.1, where the failure does not exist). The second load is conditional, as a browser's revalidation is, and must be a clean 304. Today Caddy reaches SeaweedFS over HTTP/2, SeaweedFS's 304 declares Content-Length: 327 and sends no body, and Caddy resets the stream. A browser reports that as ERR_HTTP2_PROTOCOL_ERROR on every reload of a cached files. image. CORS on delivery is the deployment's own: - exactly the API origin (and the Dashboard origin when split) is allowed, with Vary: Origin and nothing else; - any other origin gets no CORS header; - a preflight is answered by the proxy (204, GET and HEAD only) and never reaches the object store. Today SeaweedFS reflects every origin with PUT, POST and DELETE, and answers the preflight itself. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-06 01:19:17 +00:00
ekklesiaandClaude Opus 5.5	54ac6ab83f	test(deploy): Doctor must check the client-address configuration the API runs ... Behind the reference proxy the API runs in trusted-proxy mode, but compose.proxy.yaml gives those variables to `api` only. The documented Doctor command runs as `migrate`, so it validated an empty configuration and reported "Direct client-address mode" for an installation that trusts its proxy. That is what the first production installation saw. Fails today: - deploy.test.ts: the proxy overlay gives `migrate` no client-address environment; - doctor.test.ts: the check does not say whose configuration it read; - smoke-deploy.sh: Doctor through the proxy overlay does not report trusted-proxy mode (Docker). Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-06 00:42:38 +00:00
ekklesiaandClaude Opus 5.5	f50e8f4201	test(deploy): word the long-watch checks for any watch length ... The recycle step's checks spoke of "the realtime recycle" even when run with a watch shorter than the five-minute connection age, as module CI does. They now say what they check: live for the whole watch (plus "across a realtime recycle" when the watch is long enough), and never remounted. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-05 19:09:51 -05:00
ekklesiaandClaude Opus 5.5	ff8a3e8097	test(deploy): add opt-in display-device scenarios to the split smoke ... Reproduction harness for what the first production Signage deployment found. With EKKLESIA_SMOKE_DISPLAY_DEVICE=1, the split smoke starts a second headless Chromium (the "kiosk") whose profile directory is a Docker volume. It pairs that kiosk through the real flow, closes it cleanly, restarts it on the same profile, and then runs injected-failure scenarios: two pages on one credential, a connectivity blip, one refused viewer-session request, one refused realtime connection, a cross-origin image-caching probe, a full realtime recycle, and revocation. Every DevTools command and page-side request has its own deadline, and each step has a budget. A step that overruns prints the exact call it was waiting for. The proxy's "aborting with incomplete response" lines are listed afterwards by UTC time and path only. Off by default: several scenarios expect Signage and fail on today's v0.1.1, by design. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-05 18:25:12 -05:00
ekklesiaandClaude Opus 5.5	f63f80f2f0	feat: support split Dashboard and API origins (ADR 0045) ... An installation can now serve the Dashboard and the API on sibling hostnames (dash./api.) beside the default same-origin topology, from one image and with configuration alone. - The Dashboard learns its API origin at run time: the built page carries one empty <meta name="ekklesia-api-origin">, which the API fills with its identity base URL's origin at startup, before computing the page's ETag. The shell accepts only a canonical http(s) origin and otherwise fails closed without making a request. The build-time EKKLESIA_API_BASE_URL is gone from the bundle; the development server injects the same element. - The display host stays on the API's origin, so its device cookies, requests, and offline cache are unchanged. - The API trusts its own origin (trusted origins plus the identity base URL), as Better Auth already does, so the display page's mutations pass the origin check without operators listing it. - Doctor validates EKKLESIA_DASHBOARD_ORIGIN exactly as the API's startup does (it previously skipped it), reports the topology without printing hostnames, and warns when split hostnames are not siblings. - The module UI contract states the CORS header limit (safelisted headers plus Content-Type, safelisted response headers only). - Reference deployment: Caddyfile.split.example (Dashboard hostname serves / and its script; API hostname serves /api/*, /display/*, and the display script; each refuses the other's paths) and EKKLESIA_DASHBOARD_HOSTNAME in the proxy overlay and env examples. - The deploy smoke test runs either topology (CI runs both). The split run installs the module template as a test-only module, checks per-hostname routing and exact CORS, then drives a digest-pinned headless Chromium over the DevTools protocol, with no added dependency: sign-in on the Dashboard hostname, the session cookie host-only on the API hostname, the module UI imported cross-origin and its credentialed request succeeding, the display and its service worker on the API hostname, and sign-out. ADR 0045 is marked Accepted. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-03 14:47:36 -05:00
ekklesiaandClaude Opus 5.5	278e66049f	fix(ci): isolate concurrent runs on a shared Docker daemon and explain readiness failures ... PR #51's migration-smoke failed 0.7 s after the build: the suite pinned PostgreSQL to an ephemeral port but inherited S3_PORT=8333 from .env.example, so concurrent runs on one runner (Gitea ignores workflow concurrency) contended for one host port. Compose's own error was discarded, so the failure said only that the services "did not become ready". Isolation, from an audit of every script CI runs: - test-migrations-integration.sh: S3_PORT=0, like POSTGRES_PORT=0. - test-migrations-integration.sh and smoke-infrastructure.sh: project names gain a random suffix; run id plus PID alone is not unique when job containers share low PIDs. - smoke-deploy.sh: the edge /24 is chosen from those no network on the daemon uses, and the first `up` chooses again when a concurrent run wins a race for the same subnet (Docker's address-pool overlap), up to five times. - CI image-build: the image tag includes the run id and attempt, so a pull request and a push of the same commit cannot remove each other's image. - Already isolated: every other published port (ephemeral), the TLS suite's container and network (random), smoke staging directories and image tags (random). Diagnostics: scripts/lib/compose-diagnostics.sh prints the failed `up` command's output, `docker compose ps`, and the last 40 log lines of each service, all redacted (supplied literals, credential-looking NAME=value pairs, URL user information, Authorization headers) with terminal control sequences stripped. All three scripts use it at every readiness check; the infrastructure smoke's unredacted full-log dump is replaced by it. tests/ci-scripts.test.ts pins ephemeral ports, unique project names, the subnet choice, the CI image tag, the diagnostics, and the redaction itself (run through bash). Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-03 12:15:01 -05:00
ekklesiaandClaude Opus 5.5	167b4c4f14	feat(deploy): add the reference deployment Compose project ... Implement ADR 0044's reference deployment as a base Compose file plus overlays, so an installation that already runs a proxy can use the base alone. - compose.yaml: api, postgres, object-storage, and the operator-only migrate (profile ops, plan by default). No published port. api and migrate run init, read-only, tmpfs /tmp, cap_drop ALL, no-new-privileges. postgres is only on the internal data network. - TLS everywhere from one installation-private CA: PostgreSQL TLS 1.3 only, with pg_hba rejecting every non-TLS connection, and the API on verify-full via EKKLESIA_DATABASE_CA (PEM text). SeaweedFS serves S3 over HTTPS (ADR 0030 requires https in production), trusted by the API through NODE_EXTRA_CA_CERTS. No Core change. - compose.proxy.yaml + Caddyfile.example: Caddy pinned by digest, ACME HTTP-01 (DNS-01 documented), routes /, /api/*, /display/*, /assets/* to api and refuses everything else; the storage hostname preserves Host. The API trusts exactly the proxy's fixed /32 on an edge network whose dynamic range excludes the fixed addresses; Caddy overwrites X-Forwarded-For and strips caller-supplied forwarding headers. - compose.tunnel.yaml: cloudflared pinned by digest, token from its own env file; Caddy honors CF-Connecting-IP only from its fixed address. - Four per-service root-owned env files, examples with no values; scripts/init-tls.sh (idempotent, never overwrites a key) and scripts/gen-secrets.sh (prints only). - CI: pnpm deploy:config in ci:verify for all three combinations, and a deploy-smoke job (scripts/smoke-deploy.sh) proving readiness, the Dashboard, signed storage delivery, the client-address chain, initial owner sign-in/out, verify-full database TLS, and Doctor through the proxy, against disposable services. tests/deploy.test.ts pins the structural guarantees. - ADR 0044 (still Proposed) amended to match: API-to-storage HTTPS, DNS-01 needs a custom Caddy build and tunnel-only needs DNS-01, the tunnel's origin TLS settings live in the Cloudflare dashboard, port 80 serves HTTP-01, and secrets are one env file per service. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-01 20:59:38 -05:00
ekklesiaandClaude Opus 5.5	fc422b6d8d	fix(packages): declare runtime imports as production dependencies ... @ekklesia/module-sdk imports drizzle-orm at run time but declared it only as a peer and a development dependency. A workspace package is linked into its consumers as a directory, so its imports resolve from its own node_modules, where a consumer never satisfies a peer; a production install omits development dependencies. In the production image this made every module with a schema fail: the API exited at startup and Doctor reported NOT READY. - Move drizzle-orm to module-sdk's dependencies, keeping the peer. - Move react to @ekklesia/ui's dependencies, keeping the peer. The new guard flags it the same way; it is bundled at build time today, so it was not a live failure. Both lockfile entries keep the identical resolution, so nothing new is installed and the shell bundles still contain one React. - Add the boundary rule runtime-imports-are-production-dependencies: code a package ships (src/, bin/, excluding tests and .d.ts) must declare every runtime import in dependencies or optionalDependencies. Type-only imports are exempt; .tsx/.jsx implies react (automatic JSX runtime). Fixtures cover peer-only, dev-only, JSX, undeclared, and the accepted cases. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-01 19:29:35 -05:00
ekklesiaandClaude Opus 5	c444ff570b	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]>	2026-08-27 07:47:10 -05:00
ekklesiaandClaude Opus 5	07835b7b56	feat: give module UI real stylesheets, and every artifact its own root ... ADR 0023 refused stylesheet imports for a good reason: esbuild would emit a `.css` sidecar beside the artifact, nothing would declare it, no host would fetch it, and it would work in a local test and silently do nothing in a real host. Inline style objects were the whole story. They cannot express `:hover`, `:focus-visible`, `:disabled`, `@media`, or `@keyframes` — so an accessible focus treatment was not expressible, and the shared elements added in the previous commit are built from real CSS for exactly that reason. Compile the stylesheet into the artifact instead of beside it. A module imports plain `.css`; the canonical builder resolves local `@import`s through a nested bundle and turns each file into its compiled text, which the author declares as `defineModuleUi({ styles })`. One declared file still contains everything: nothing extra to publish, nothing to fetch, and no way for CSS to become an asset nobody serves. The build additionally fails if a CSS output ever appears beside an artifact, so a future loader change cannot bring the sidecar back. Two rules are enforced with their own codes: a module stylesheet may reference `--ekklesia-*` and never declare one, and every `@import` must resolve locally or the artifact would fetch styles at run time. Plain `.css` only; other dialects are a toolchain decision needing their own ADR. Then make the isolation real. The generic loader mounts every browser artifact — primary, display, and later a contributed renderer — inside an open Shadow DOM root it creates, installs the artifact's stylesheet there, and hands the artifact an element inside it. Shadow DOM is the one mechanism a browser actually enforces; a class prefix or a "scope your selectors" instruction is a convention one mistake defeats, and the failure mode is a module silently restyling the Dashboard. It applies unconditionally, including to artifacts with no stylesheet, because a conditional boundary is one a module can fall out of by editing a source file. Both wrappers are `display: contents` through base rules installed before the artifact's own, so layout is unchanged and a full-viewport display can still override `:host`. Unmount removes the whole root in a `finally`, so a cleanup that throws cannot leave styles behind, and remounting cannot accumulate a second copy. This is a correctness boundary for styles and is not described as a sandbox: the root is `open` precisely because module code is trusted, same-realm code that could reach `document` anyway. An artifact's DOM is no longer a direct child of the host's element, so the mount ABI is versioned explicitly. `defineModuleUi` stamps `MODULE_UI_ABI_VERSION` so it can never drift from the SDK the artifact compiled against, and a version-1 artifact fails with its own code — "rebuild your module", not a typo hunt. No dual acceptance, matching every manifest cutover here. Migration is one `pnpm build`. `pnpm boundaries` allows `.css` only under `src/ui/` and `src/display/`: a stylesheet anywhere else in a module is the undeclared sidecar again, just relocated. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-27 07:21:14 -05:00
ekklesiaandClaude Opus 5	e03d38fcab	feat: give every Ekklesia screen one set of design tokens and elements ... Modules have owned their own UI since ADR 0021, but the platform has never said what that UI should look like. Every screen here — the Dashboard shell, the display host, the module template — invented its own hex colours, font stack, spacing, and radii, and they already disagreed. A module author had no vocabulary for "the ordinary panel background", so the only available answer was to invent one, and two modules would invent two. Add `@ekklesia/design-tokens`: one validated, enumerable registry of semantic tokens. A token declares a name, label, description, and default value; its category and `--ekklesia-*` identifier are derived from the name, so it can never claim one category while being named for another. Construction rejects duplicates, malformed names, unknown categories, empty or overlong text, and any value that is not a bounded literal — no declaration terminator, rule block, comment, at-rule, `url(`, `!important`, escape, control character, or markup. A registry that constructs can therefore be emitted as CSS without escaping, because nothing needing escaping can be in it. That validation is also what makes a future theme editor implementable rather than aspirational. Add `@ekklesia/ui`: button, icon button, text input, select, checkbox, field wrapper, panel, dialog, tabs, table and list primitives, badge, toast, and empty/error/loading states — every value a token reference, with real `:focus-visible` treatment and status that never depends on colour alone. Deliberately small: an element earns its place when two consumers need it. The stylesheet is a string rather than a `.css` file so the identical bytes install into a document or an isolated artifact root, and so hover, disabled, and focus-visible are real CSS rather than JavaScript approximations of them. `pnpm boundaries` opens exactly two shared roles to modules, by name — every other role stays rejected — and pins both design packages to the bottom of the presentation stack. Both are browser-safe by construction, proven by a real compile of module-shaped source in which `process.env` must fail to typecheck. The shell installs the defaults at its document root for the Dashboard and the display; custom properties inherit into module artifacts, so a module reads `var(--ekklesia-…)` with nothing to import at run time and nothing for a host to forget to pass. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-27 06:59:44 -05:00
ekklesiaandClaude Opus 5	b9ca0d560d	feat: add host-provided module object storage ... `manifest.storage.buckets` has existed since manifest version 1 and meant nothing — discovery validated it and no code read it. This turns it into a real capability, which is what stands between Announcements and the module system: that product currently fetches a hardcoded LAN S3 endpoint, parses ListObjectsV2 XML by hand, and hands the browser direct object URLs. - A module declares a logical bucket and receives a scoped facade at `context.storage` — list, head, get, put, delete. The contract names no provider: no endpoint, region, credential, or physical bucket is reachable from it, which is what lets the same module run under a future standalone host over its own or a shared S3-compatible service. - Core's first provider speaks S3 through the AWS SDK. SeaweedFS is the deployment target (ADR 0004), never an API name. Probing the pinned image found `CreateBucket` reporting `BucketAlreadyExists` rather than AWS's `BucketAlreadyOwnedByYou`; treating only the AWS spelling as success would have failed every second boot. A live test pins it. - Logical → physical mapping is deterministic and collision-safe: an installation prefix, the module and bucket ids joined by `--` (which cannot occur inside either identifier, so `a-b`+`c` and `a`+`b-c` cannot collide), and a digest over the full untruncated identity. Two modules declaring `assets` always get separate namespaces; neither can see the physical name. - Declaring a bucket is now a requirement: with no provider configured the module is `blocked · storage_unavailable` through ADR 0028's existing resolver, propagating to required dependents. An installation with no object storage stays a complete deployment. - Binding availability is not provider health. Eligibility asks whether storage is configured, never whether it answered; bucket creation is lazy on first use so a storage outage cannot stop the platform booting; a running module whose store blinks stays running and retries. Nothing deletes a bucket. - Credentials are deployment-supplied, never persisted, never routed through module configuration, and never visible to modules, module UI, diagnostics, or API responses. Provider errors translate to a closed code set carrying no endpoint, bucket, request id, or XML. - Retires ADR 0029's transitional `bucket` configuration key. No manifest version change. The template declares no bucket, so it still runs without S3. See ADR 0030. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-23 08:45:53 -05:00
ekklesiaandClaude Opus 5	616c1d4834	feat: mount discovered module UI in a minimal Ekklesia browser host ... Phase 6C pass 2. Every link in the module UI chain existed except the one that closes it: a module could be authored, built, validated, published at a browser URL, and loaded by a generic loader — and nothing in Ekklesia did any of it. There was no browser application at all. Two pieces were missing. A browser could not discover what to mount, and it must not work that out for itself. GET /api/v1/module-ui is the inventory: per publishable module, its id and version, the server-produced artifact URL, the server-produced root of the module's own API, and the subset of that module's declared permissions the caller holds. Five fields, each because building a ModuleUiHostContext needs it — no filesystem paths, and no name/icon/folder/order, because navigation metadata is a design that does not exist yet. Its module set is the ADR 0025 publication registry rather than a rescan, so the inventory and the artifact route cannot disagree. It requires a new Core permission, core.modules.ui.read (baseline authenticated), because it is precisely the enumeration the anonymous artifact route deliberately withholds. Both URLs are server-produced. moduleUiArtifactUrl already existed; moduleApiBaseUrl is now exported and moduleRoutePath builds on it, so each URL shape has exactly one author. Without it the shell would hardcode /api/v1/modules/<id> — the prefix ADR 0022 forbids a module UI from spelling, reappearing in the host instead. surfaces/shell (@ekklesia/shell) is the repository's first surface: a small React application built to static files by its own esbuild script. It resolves the principal, fetches the inventory, builds the host context entirely from server-derived data, and hands the artifact URL to @ekklesia/module-ui-host. One frame per selection — keyed by module identity — defeats the stale-load race; the host owns the container, the loading state, and every failure, so a broken module costs its own panel rather than the shell. The shell statically imports no module, and both levels are checked: no source import may name a module, and the emitted bundle must contain exactly one dynamic import (the loader's) with no module id, no /api/v1/modules, no eval, and no blob URL. Permission hints come from Core's own evaluator and stay presentation-only — the end-to-end test has a UI holding no grant call its API anyway and still receive 403. Surfaces may now depend only on browser-safe shared roles; @ekklesia/contracts is deliberately excluded, since its barrel pulls Drizzle's types and Node's globals into the browser — the hole ADR 0024 closed one layer down. Not the Dashboard: no navigation, grouping, icons, ordering, design system, or routing. The selector is a list of module ids. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-22 08:55:44 -05:00
ekklesiaandClaude Opus 5	44e676f0df	feat: close the browser boundary and add the generic UI host loader ... Two gaps stood between the module UI contract and a host that could use it. ADR 0023 recorded the first honestly but never diagnosed it: a module UI file compiled with `"types": []` could still typecheck `process.env`. The second was simply missing — nothing imported a compiled artifact, checked its identity, mounted it, or tore it down. The leak was one type-only import, bisected against the real type graph rather than guessed. `@ekklesia/module-ui-sdk` imported `type { EkklesiaPrincipal } from "@ekklesia/contracts"`. Importing contracts/identity alone is clean and importing Zod alone is clean, but contracts exposes a single barrel entry, so that one import reached module-database, whose Drizzle types re-introduce Node's globals. The runtime was never affected — the import was erased and host-context.js is `export {}` — but a type-graph leak is still a real boundary failure, because it silently permits code that cannot run in its target environment. The fix is not a narrower import path. The SDK now has no dependencies at all, so there is no graph to leak through and no future contracts change can reopen this. It owns `ModuleUiPrincipal`: the same shape ADR 0022 chose, with the Zod brand dropped. That brand encodes a server-side parsing guarantee a browser cannot produce, and it is the same reason `permissions.has` already took a plain string. An Ekklesia host still passes its own `EkklesiaPrincipal` straight through — a branded string is assignable to `string` — while a standalone host builds the literal. Proven the way an author experiences it: two fixtures compiled under the exact project a module uses, one supported and one deliberately reaching for `process`, with the second required to fail on that specific name. `@ekklesia/module-ui-host` is the generic loader, in its own package because the SDK is bundled into every module artifact and host-only loader code has no business shipping there. The boundary checker enforces both directions: modules may not depend on the loader, and the loader may depend only on the SDK plus dev-time tooling. The distinction that shaped the design: Core resolves `entrypoints.ui` to an absolute path on the server's disk, and a browser needs a URL. A loader that accepted the path would test green on a server and fail in every real host, and would quietly own asset publication. So the loader takes a browser-loadable URL and knows nothing about how one is obtained. Ekklesia has no route that publishes installed artifacts, so this is precisely: loader complete, publication deferred. Nothing can mount an installed module UI yet, and the docs say so rather than implying otherwise. Dynamic import is `(url) => import(url)` with a non-analyzable specifier, kept as a runtime import so a host does not statically bundle every installed module or need a hardcoded registry. It is injectable for bundlers needing their own escape hatch, and deliberately not `eval` or `new Function`, which would cost a host `unsafe-eval` in its CSP. Identity is validated through the SDK's existing parser before `mount` runs, so a stale or mismatched bundle never renders. Contract violations propagate unwrapped; the loader adds only import and mount failure codes, sanitized, with the cause attached. Unmount is idempotent, safe when a module returned no cleanup, and marks an instance unmounted before running cleanup so a throwing cleanup surfaces once and never re-runs. A failed mount registers no cleanup. Each instance owns its own state, so two mounts coexist. The loader never mutates the host's container — not on success, failure, or unmount. Tests prove all of it against real module URLs (`data:`, which both browsers and Node import natively) rather than filesystem paths, including one artifact built by the canonical Pass 2 pipeline and run under both an Ekklesia-shaped and a standalone-shaped context. Core, apps/api, and the contracts package are untouched; discovery remains inert. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 21:44:42 -05:00
ekklesiaandClaude Opus 5	8d651c427d	feat: define the module UI authoring model and host contract ... ADR 0021 established that a module may own UI and added a statically validated, never-executed `entrypoints.ui` path, but deliberately left five questions open: what the artifact exports, what a host provides, how one artifact runs under both Ekklesia and a standalone host, what the browser-side trust model is, and how module UI avoids being welded to a Dashboard that does not exist. This answers them. React and TypeScript are the supported module UI authoring model. The repository already leaned this way: `packages/typescript-config` ships a `browser.json` preset and a `react-native.json` preset with `"jsx": "react-jsx"`, and ADR 0002 names browser and React Native configurations. One framework is supported; every other stays rejected. React is deliberately not part of the contract. A module's compiled artifact default-exports `defineModuleUi({ id, version, mount })`, and `mount(container, context)` takes a DOM element and returns an unmount function. `id` and `version` are build-artifact identity markers a host verifies against the manifest, mirroring `defineModuleRuntime` exactly. A host needs an element and a context, never a matching rendering library, so a module's framework, a host's framework, and the platform boundary between them stay independent. The contract lives in a new `@ekklesia/module-ui-sdk` rather than in `@ekklesia/module-sdk`, for a concrete reason: that package re-exports all of `@ekklesia/contracts`, so routing module UI through it would drag Zod, Drizzle, and semver into every browser bundle. The new package has no runtime dependencies, and its one dependency on contracts is type-only — the emitted `host-context.js` is `export {};`, and a test pins that so it cannot regress. The host context is four members: `moduleId`, `api`, `principal`, and `permissions`. Navigation, theme, module configuration, organization context, and diagnostics are deliberately absent; each needs a design that does not exist. Module UI reaches its backend through `api.request(path)` with a path relative to its own API root and never constructs `/api/v1/modules/<id>/...`, which is Ekklesia's private deployment detail — a module that builds that URL is silently unhostable anywhere else. One fixture artifact is mounted under two hosts with different origins and URL shapes to prove it. Client-side permission hints are presentation only, and both the docs and a test say so plainly: a denied hint does not stop the module from calling its API, because server-side `requirePermission` is the only authority. Module UI is trusted code in the host's own browser realm — no iframe, no sandbox — which matches the backend model rather than overstating it, since a module's server half already holds the API's database authority. The boundary guard is narrowed precisely, not removed: `.tsx`, `react`, and `react-dom` are un-denied and modules may depend on the new `module-ui-sdk` role. `.jsx`, `.css`, every other framework, `react-router-dom`, `react-native`, and `@vitejs/plugin-react` stay denied, layer rules are untouched, and an unsupported framework aliased behind an allowed name (`"react": "npm:vue@3"`) is resolved and rejected by its real target. Fixtures prove each case, including that module UI source still cannot import Core. Core, apps/api, and the manifest contract are untouched. Discovery still validates the `entrypoints.ui` path and never evaluates it; hosts perform their own dynamic import and validate the result with `parseModuleUiExport`. No Dashboard shell, UI runtime, navigation, grouping, standalone host, build or styling pipeline, installer, hot-loading, or feature module is added. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 20:52:47 -05:00
ekklesiaandClaude Opus 5	27088fc054	fix: run the TLS integration harness under a containerized job ... The `migration-smoke` job fails on the Gitea runner at `docker port ekklesia-database-tls-<pid> 5432` with `no public port '5432' published`; the later invalid-URL and `ECONNREFUSED 127.0.0.1:5432` failures all cascade from it. Gitea executes the job inside a container and drives sibling containers through the runner's Docker daemon. The harness held two host-only assumptions, both reproduced in a nested job container and fixed here. Bind-mount source paths are resolved by the daemon against the runner host's filesystem. The certificate directory is created in the job container's `/tmp`, which does not exist there, so the daemon silently creates an empty directory, the entrypoint's `cp` fails, the container exits, and `docker port` reports no published port for an exited container. The material is now transferred with `docker cp` into the created-but-not-yet-started container, which crosses the daemon boundary correctly in both topologies, and only the server leaf and its key are transferred — both CA private keys stay in the harness directory. A published port lands on the runner host's loopback, a different network namespace from the job container's; measured, a container the daemon published at `127.0.0.1:32907` is `ECONNREFUSED` at that address from inside the job container. Under a containerized job the harness now publishes nothing and joins both containers to one isolated user-defined network, reaching PostgreSQL by container DNS on 5432. Direct-host runs keep a random port pinned to loopback via Docker's `127.0.0.1::5432` form. `compose_job_network_job_container` exports the topology decision the integration script already made, so there is still exactly one detector. Every TLS assertion is preserved, and the certificate identity is generated from the host actually connected to — `localhost` directly, the container's DNS name otherwise. The mismatch and chain-only controls use the TLS container's address on the isolated network rather than a hardcoded one, and the certificate carries no IP SAN, so verify-full still fails with `ERR_TLS_CERT_ALTNAME_INVALID`. Correcting one measurement in passing: chain-only verification does not skip the identity check. For an IP host `pg` omits `servername` and hands `tls.connect` a bare socket with no host, and `net.Socket._host` is null for an IP literal, so Node checks the fixed fallback name `localhost` — never the address dialled. A certificate whose only SAN is `DNS:example.invalid`, reached chain-only over `127.0.0.1`, is rejected with `Host: localhost. is not in the cert's altnames`. The direct-host control therefore only ever passed because its SAN was `DNS:localhost`. The SAN set now always includes that fallback name so the control proves the same gap in both topologies, and the stale claim is corrected in the transport doc comment. No production behavior changes. Teardown also removes the container's anonymous volume, the isolated network, and the job container's attachment, after success and failure alike. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-07-29 21:42:26 -05:00
ekklesia	02ee3ccd80	feat: add Ekklesia doctor command	2026-07-21 10:42:21 -05:00
ekklesia	831a48187c	test: add PostgreSQL migration integration coverage	2026-07-21 09:37:15 -05:00
ekklesia	2465d9c1f7	runner fix	2026-07-13 20:19:30 -05:00
ekklesia	d9489384c1	chore: harden repository guardrails	2026-07-12 21:20:58 -05:00
ekklesia	192a6514cf	chore: establish Ekklesia platform foundation	2026-07-12 20:28:19 -05:00