Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .github/workflows/cloudflare-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
name: Prepare Cloudflare release
on:
workflow_dispatch:
inputs:
profile:
description: Checked-in installation profile (not the placeholder example)
required: true
type: string
permissions:
contents: read
jobs:
prepare:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.3
- uses: actions/setup-node@v4
with:
node-version: 22
- run: bun install --frozen-lockfile
- run: bun run check
- run: bun run test:workerd
- name: Prepare reviewable release (offline)
env:
PROFILE: ${{ inputs.profile }}
run: bun run cloudflare:prepare "$PROFILE" cloudflare-release > cloudflare-review.json
- uses: actions/upload-artifact@v4
with:
name: cloudflare-release-${{ github.sha }}
path: |
cloudflare-release/
cloudflare-review.json
if-no-files-found: error
14 changes: 14 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,20 @@ on:
permissions:
contents: read
jobs:
infrastructure:
runs-on: ubuntu-24.04
defaults:
run:
working-directory: infra/cloudflare
steps:
- uses: actions/checkout@v4
- uses: opentofu/setup-opentofu@v1
with:
tofu_version: 1.13.2
- run: tofu init -backend=false -input=false
- run: tofu fmt -check -recursive
- run: tofu validate
- run: tofu test
verify:
runs-on: ubuntu-24.04
steps:
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,10 @@ Documentor has matching opt-in installation through `publish.site.concourse`.

The API uses `/__concourse/` on the publication's own origin. Configure Access,
site membership, a migrated D1 database and a Worker route before enabling it.
There is no production debug-login option. See the deployment guide for the
owner-selected `helix.synaptiq.tools` target and staged rollout.
There is no production debug-login option. Use the small [Terraform foundation](infra/cloudflare/README.md) and
[Wrangler release procedure](docs/helix/05-deploy/first-slices.md) for the
owner-selected `helix.synaptiq.tools` target. `cloudflare:prepare` works offline;
`cloudflare:deploy` requires a reviewed release digest and never runs migrations.

Install the repository pre-commit gate with `git config core.hooksPath .githooks`.
Use the installed HELIX catalog; methodology templates are not vendored here.
Expand Down
16 changes: 16 additions & 0 deletions deploy/cloudflare/profile.example.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"name": "helix-concourse",
"account_id": "REPLACE_ACCOUNT_ID",
"compatibility_date": "2026-08-06",
"workers_dev": false,
"preview_urls": false,
"routes": [
{ "pattern": "helix.synaptiq.tools/__concourse/*", "zone_id": "REPLACE_ZONE_ID" }
],
"vars": {
"SITES": "[{\"id\":\"helix\",\"origin\":\"https://helix.synaptiq.tools\",\"issuer\":\"https://REPLACE_TEAM.cloudflareaccess.com\",\"audience\":\"REPLACE_ACCESS_AUDIENCE\",\"domains\":[\"synaptiq.ai\"],\"emails\":[]}]"
},
"d1_databases": [
{ "binding": "DB", "database_name": "helix-concourse-comments", "database_id": "REPLACE_DATABASE_ID" }
]
}
13 changes: 13 additions & 0 deletions docs/helix/00-discover/owner-input.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,16 @@ special cases from reusable protected publishing. Goal two is inline comments
on HELIX microsites for logged-in users. Existing domains and infrastructure
resource identities must survive refactoring. Provider coverage beyond the
existing Access configuration remains separately qualified.

## Hosting and deployment direction — 2026-10-29

The owner requested a Batten-hosted Concourse backend plugin on Databricks Apps
and a separate static-content plugin serving a complete publication directory
from a volume behind the Apps proxy. This is a required additional hosting
profile; Batten integration and identity/storage qualification remain design work.

For Cloudflare, the owner selected a Wrangler profile coupled with a very small
reusable Terraform module that can be consumed by Synaptiq infrastructure.
Application deployment must be repeatable and explicitly reviewed. Shared
infrastructure stays with its existing owner; preparing this package does not
authorize applying infrastructure, reading credentials or running migrations.
30 changes: 30 additions & 0 deletions docs/helix/02-design/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ Existing infrastructure owns Access/DNS; each publication owns its site inputs.
| src/browser | Inline UI and same-origin client | mountComments | shared, DOM | Server, CLI, Node/Bun |
| src/cli | Protected-host check and distribution installation | CLI | Bun/Node, shared | server/browser internals |
| infra/protected-publication | Pages/Access/DNS resource composition | Module inputs/outputs | Cloudflare provider | Site-name branching |
| infra/cloudflare | Installation foundation: publication module and protected D1 lifetime | Terraform inputs and installation output | protected-publication, Cloudflare provider | Worker code, routes or deployment credentials |
| scripts/cloudflare | Validate Wrangler profile, prepare and verify release bytes, explicit deployment command | CONTRACT-001 deployment surface | server/config public validator, Node/Bun, pinned Wrangler CLI | Browser internals, automatic migrations, Terraform mutation |

**Integration Owners**: server/auth.ts owns Access translation; server/store.ts
owns D1 SQL; browser owns DOM/UI; infra module owns provider composition.
Expand All @@ -63,6 +65,27 @@ qualify separate profiles. Cloud backup/restore and retention need a production
runbook and owner policy before real data admission. No cloud resources are
provisioned by this local build.

The supported Cloudflare installation entry point is `infra/cloudflare`.
Terraform owns Pages project/domain, DNS, Access and D1 lifetime. Wrangler owns
Worker code, bindings and `/__concourse/*` routes exclusively. Existing login
providers are referenced by ID, never recreated. The earlier
`infra/collaboration-worker` is a legacy alternative and must not manage a
Wrangler-owned Worker or route.

An installation keeps one explicit Wrangler JSON profile. Preparation runs
offline, validates the selected audience/hosts, disables workers.dev and version
URLs, and packages built Worker/configuration/migration bytes with hashes. The
separate deployment command requires the reviewed release digest and rechecks
all bytes before invoking the pinned Wrangler. It does not apply migrations or
publish static content. Its summary is desired configuration, not a cloud-state
diff; an initial infrastructure plan and live protection checks remain required.
The consumer's existing static build/sign/upload pipeline owns content releases.

Databricks Apps/Batten is an additional required hosting profile, with separate
backend and volume publication plugins. Cloudflare tooling does not establish
that profile's identity, storage or proxy guarantees and is not a portable
backend contract. No Batten runtime support is claimed by this package.

## Data Flow

1. Static page loads the opt-in component with site, source resource and revision.
Expand Down Expand Up @@ -101,3 +124,10 @@ validation. CONTRACT-001 owns the native v1 protocol; this local profile does no
claim UMF projection, generation or action qualification. Append-only SQL is the
persistence authority; unknown request members are rejected, never erased from
UMF documents. No UMF document is ingested by this slice.

Deployment uses Wrangler 4.156.0's native configuration schema, not a new UMF
model. The preparer accepts a bounded subset and fixes bundle/migration paths;
the actual pinned Wrangler dry-run verifies vendor compatibility. The release
manifest is local distribution-integrity metadata, with no UMF identity, action
or transaction semantics. The earlier UMF inspection supplies no appropriate
replacement for this provider-specific configuration.
36 changes: 36 additions & 0 deletions docs/helix/02-design/contracts/CONTRACT-001-first-slices.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,42 @@ path qualify, never substring matches in query parameters. `install-hugo.ts

## Precedence and Compatibility

### Cloudflare deployment surface

`infra/cloudflare` composes `infra/protected-publication` with a D1 database
whose lifecycle prevents destruction. It accepts that module's publication
inputs and returns `installation` (account_id, zone_id, hostname, worker_name,
database_id, database_name, audience). It MUST NOT own Worker code, bindings or
routes. The consumer pins a reviewed source revision and supplies the existing
identity-provider IDs. Neither module applies SQL or reads credentials itself.

`deploy/cloudflare/profile.example.json` demonstrates the native Wrangler
configuration subset. Profiles are JSON (comments are not accepted by the
preparation tool). Exactly one DB binding and one or more unique site routes are
required. Each route MUST match a configured site's HTTPS host and exactly
`/__concourse/*`, with an explicit zone_id. Unknown settings, environments,
assets, build hooks and alternative entry points refuse. The runtime's SITES
validator supplies membership and identity validation. The compatibility date
is pinned to the tested first-slice profile; workers_dev and preview_urls MUST
be false. Profiles contain IDs and policy, never credentials.

`bun run cloudflare:prepare <profile.json> <new-release-directory>` reads the
profile, built `dist/worker.js` and committed SQL files. It creates a new release
directory with `worker.js`, normalized `wrangler.json`, `migrations/*.sql`, and
`release.json`. It refuses existing output directories, placeholders and unsafe
routes. The manifest includes source commit, pinned Wrangler version, per-file
SHA-256 digests and a release digest over its canonical payload. Preparation
does not contact Cloudflare or inspect credentials.

`bun run cloudflare:deploy <release-directory> --approve <release-digest>` MUST
verify the digest and all file hashes, reject extra files and symlinks, validate
configuration again and require the installed Wrangler version to match before
invoking `wrangler deploy --config <release>/wrangler.json`. No automatic SQL,
Terraform apply, static publication upload or rollback is permitted. Wrong or
missing approval, changed bytes or invalid profile aborts before Wrangler starts.
The digest is a review/integrity boundary, not a signature or cloud-state plan.
The command uses the invoking operator's separately authorized credential.

Unknown protocol/config version or fields refuse. Site host/config and verified
principal take precedence over browser fields. Wire v1 is separate from any UMF
extension or native action profile. Additive wire changes need explicit version
Expand Down
41 changes: 41 additions & 0 deletions docs/helix/04-build/evidence/cloudflare-profile.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
{
"date": "2026-10-29",
"scope": "Wrangler release profile and reusable Terraform foundation; no live deployment",
"versions": {
"bun": "1.4.3",
"node": "26.12.1 (local; CI selects 22)",
"wrangler": "4.156.0",
"opentofu": "1.13.2",
"cloudflare_provider": "5.17.0"
},
"checks": {
"bun run check": "passed: strict types, lint, boundaries, build, 17 tests / 148 assertions",
"Wrangler deploy --dry-run": "passed against real prepared Worker bundle and explicit bindings; no credentials supplied; release hashes unchanged",
"bun run test:workerd": "passed existing local workerd/D1 integration",
"tofu validate": "passed, backend disabled; cached provider, local plugin execution",
"tofu test": "passed one mocked-provider plan test; no cloud-state plan or apply",
"tofu fmt -check -recursive infra/cloudflare": "passed",
"HELIX architecture and CONTRACT-001": "passed, zero findings",
"workflow YAML and git diff --check": "passed"
},
"limits": [
"No cloud credentials read, infrastructure plan/apply, deployment, or remote SQL executed.",
"Hosted CI is pending; local native runtime is not live Access qualification.",
"Existing state adoption, actual installation IDs, remote migration review, restore/retention policy and authenticated admission probes remain before production use.",
"Batten/Databricks Apps profile is recorded owner intent, not implemented or qualified here."
],
"sha256": {
"scripts/cloudflare/profile.ts": "6da3fc36b1965a23c486be03512d18a6d761213cf92b12715fa1fd0e8e1602cc",
"scripts/cloudflare/release.ts": "e49d11531b8643960f0da4d956eb0e33c609765dfb8bb276439600607a8f93f1",
"tests/cloudflare.test.ts": "95598929b72cc237f730f45180d5f8c896cca0e162e6be9add53478b6b052f66",
"deploy/cloudflare/profile.example.json": "e18b04696b54a2e8efb7049ac82c1d714119ae62fa88ebf17c6ea00c7b760467",
".github/workflows/cloudflare-release.yml": "cf5d22767f18df3da2c17f575386403e66054dd20903d15416dfe04c88c2d0ca",
".github/workflows/test.yml": "42cfb544831aea6d2aa248a6bca0705abc14138c3e66e55eff03bb615c4bdbd5",
"infra/cloudflare/main.tf": "49f6803c6449139438d8ef4f1f34427ce69e70d18bc711fa27f47d84a8fca265",
"infra/cloudflare/variables.tf": "8df21afae858b3ac869efc54098d2f8371a49b63642cccb41db618609aa4dc9f",
"infra/cloudflare/versions.tf": "c04e2e72d3ba27187accd645f0f27e7a6791ee299b7f6b41702cd540a31d67ab",
"infra/cloudflare/tests/foundation.tftest.hcl": "46a21e609db4c436df42d8f603558517dc322c0bfd977046bcce92bf8fe0465e",
"package.json": "0b59bc99c5f9d14b85b4d77a9bdbc007b5871df6dcc5177864f83cb9eec23bae",
"bun.lock": "aff1f2017e1bf71977bcbeaa6803af2f600d0f44fdd62af202152878af518a40"
}
}
14 changes: 13 additions & 1 deletion docs/helix/04-build/first-slices-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,19 @@ login, validation/error/replay states covered. Destructive actions are absent.
Service diagnostics contain only generic outcome/status; no OTel receiver
integration is claimed. Add OTel wiring before broader production operations.

## Observed results
## Cloudflare packaging follow-up

Owner selected Wrangler plus a minimal reusable Terraform foundation. Implement
`infra/cloudflare`, an example native Wrangler profile and offline preparation /
explicit digest-approved deployment commands. Test route/profile refusal,
artifact tampering and approval failure before any subprocess invocation; run
the actual pinned Wrangler dry-run against a prepared bundle. Validate the
module against Cloudflare v5 without a backend or credentials. Keep migrations,
existing-state adoption, live protection verification and production data
admission separately reviewed. No change to another repository is needed to
prepare the consumable module and example.

## Observed first-slice results

See evidence/first-slices.json for source hashes, scoped passing results and open
cloud gates. The actual Worker bundle passes local D1 execution; real HELIX
Expand Down
Loading
Loading