Develop

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "includeCoAuthoredBy": false
+}

.claude/skills/cloudflare-tunnel/.env.example

@@ -0,0 +1,64 @@
+# Cloudflare credentials for NAMED tunnels — persistent hostnames on a zone you
+# own, instead of a quick tunnel's throwaway *.trycloudflare.com.
+#
+# Copy to `.env` BESIDE THIS FILE and fill it in. That path is gitignored by the
+# repo-wide `.env` rule, and every script that touches it asks
+# `git check-ignore` first and REFUSES to read or write a token that git could
+# take. Verify yourself before you paste anything:
+#
+#     git check-ignore -v .claude/skills/cloudflare-tunnel/.env
+#
+# Nothing here is required. With no `.env`, every rig falls back to a quick
+# tunnel exactly as before — named mode is an addition, not a replacement.
+#
+# ⚠ THE TOKEN SCOPES TO A ZONE, NOT TO A HOSTNAME. There is no "only these three
+#   subdomains" grant in Cloudflare. A token that can edit DNS in your zone can
+#   edit ANY record in it. Use a zone you are willing to hand to a dev script.
+#   SKILL.md → "Named tunnels" has the exact minting steps and what each
+#   permission is for.
+
+# API token. Minted at
+#   Cloudflare dashboard → My Profile → API Tokens → Create Token → Custom token
+# with exactly two permissions:
+#   Zone    → DNS               → Edit   (Zone Resources: Include → your zone)
+#   Account → Cloudflare Tunnel → Edit   (Account Resources: your account)
+CLOUDFLARE_API_TOKEN=
+
+# The zone the hostnames below live in. The account id is read OUT of the zone
+# record, which is why no account-read permission is needed.
+CLOUDFLARE_ZONE=example.org
+
+# Optional: only if the token can see more than one account and the zone lookup
+# picks the wrong one.
+#CLOUDFLARE_ACCOUNT_ID=
+
+# One hostname per rig; each gets its own tunnel. Leave a line blank or absent
+# and that rig stays on quick tunnels.
+#
+# The app hostname serves the frontend AND Keycloak through caddy's path mux
+# (/realms/*, /resources/* → Keycloak, /objects/* → the object store, everything
+# else → SvelteKit), which is what makes the OIDC redirect work from outside.
+HACKAGON_HOSTNAME=hackagon.example.org
+PLAUSIBLE_HOSTNAME=plausible-hackagon.example.org
+OPENREPLAY_HOSTNAME=openreplay-hackagon.example.org
+
+# The k3d chart rig (.claude/skills/k3d-chart-rig/scripts/tunnel.sh) takes TWO
+# names on ONE tunnel: the helm chart routes the app and Keycloak by HOST, on
+# two separate Ingresses, so there is no single name that reaches both.
+#
+# ⚠ BOTH ARE ONE LABEL DEEP, DELIBERATELY. Cloudflare's free Universal SSL
+# covers the apex and one label — `example.org` and `a.example.org` — and
+# NOTHING below that. `auth.k3d-hackagon.example.org` gets no certificate at the
+# edge and answers a TLS handshake with alert 40, which reads to a browser as a
+# broken site rather than as a missing certificate. Keep them siblings unless
+# the zone has Advanced Certificate Manager.
+K3D_HOSTNAME=k3d-hackagon.example.org
+K3D_AUTH_HOSTNAME=k3d-auth-hackagon.example.org
+
+# Optional: tunnel names as they appear in the Cloudflare dashboard. Defaults
+# below. Change them if two checkouts share one Cloudflare account, or the
+# second one will reuse the first's tunnel and repoint its DNS.
+#HACKAGON_TUNNEL_NAME=hackagon
+#PLAUSIBLE_TUNNEL_NAME=hackagon-plausible
+#OPENREPLAY_TUNNEL_NAME=hackagon-openreplay
+#RIG_TUNNEL_NAME=hackagon-k3d

.claude/skills/cloudflare-tunnel/scripts/down.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Stop all tunnels to this stack — the compose quick tunnel, the named tunnel's
+# container, and any generic port tunnels — and undo the OIDC rewiring.
+#
+# THE NAMED TUNNEL'S HOSTNAME AND DNS RECORD SURVIVE THIS, on purpose. Stopping
+# the container is "take the link down for now"; the whole value of a named
+# tunnel is that the same hostname comes back on the next up.sh, with the issuer
+# wiring still correct. To give the hostname up for good — delete the tunnel and
+# its DNS record from Cloudflare — that is a separate, explicit act:
+#
+#   bash .claude/skills/lib/cf-named-tunnel.sh destroy hackagon <hostname>
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$HERE/../../../.." && pwd)"
+COMPOSE_FILE="$ROOT_DIR/.devcontainer/docker-compose.yml"
+case "$(uname -s)" in
+MINGW* | MSYS*)
+    export MSYS_NO_PATHCONV=1
+    export MSYS2_ARG_CONV_EXCL="*"
+    COMPOSE_FILE="$(cygpath -m "$COMPOSE_FILE")"
+    ;;
+esac
+# Stop the built server on :8082 first. `auth-wire.sh --restore` deliberately
+# leaves a running one alone (it would be a hole in the public link mid-suite),
+# so if this did not kill it the box would keep a server pinned to a tunnel
+# issuer for a tunnel that no longer exists. No-op when nothing is running.
+# (It never owned :8081, so `vite dev` needs no handover — that used to be this
+# step's real job, and the reason a suite run blacked out the public link.)
+docker compose -f "$COMPOSE_FILE" exec -T -u vscode -e USER=vscode dev \
+    bash -lc 'cd /workspaces/hackagon && bash .claude/skills/cloudflare-tunnel/scripts/prod-serve.sh stop' ||
+    echo "warn: prod-serve stop skipped (dev container not running?)" >&2
+
+# If a --with-auth run rewired the OIDC issuers, put them back too (no-op
+# when there is no config.local.yaml to delete; skipped if the dev container is
+# down, in which case the next `just up` still needs a manual --restore).
+docker compose -f "$COMPOSE_FILE" exec -T -u vscode -e USER=vscode dev \
+    bash -lc 'cd /workspaces/hackagon && bash .claude/skills/cloudflare-tunnel/scripts/auth-wire.sh --restore' ||
+    echo "warn: auth restore skipped (dev container not running?)" >&2
+
+docker compose -f "$COMPOSE_FILE" --profile tunnel rm -sf tunnel caddy 2>/dev/null || true
+
+# THIS STACK's named tunnel only. `cf-named-*` also covers the plausible and
+# openreplay rigs, which have their own hostnames and their own down.sh — taking
+# an analytics dashboard offline as a side effect of stopping the app's link is
+# exactly the kind of over-broad cleanup that gets discovered days later.
+docker rm -f "cf-named-${HACKAGON_TUNNEL_NAME:-hackagon}" >/dev/null 2>&1 &&
+    echo "stopped cf-named-${HACKAGON_TUNNEL_NAME:-hackagon}" || true
+
+for name in $(docker ps --format '{{.Names}}' | grep -E '^cf-quicktunnel-' || true); do
+    docker rm -f "$name" >/dev/null
+    echo "stopped $name"
+done
+echo "tunnels down"
+echo "(a named tunnel's hostname and DNS record are kept — the next up.sh reuses"
+echo " them. Give them up with: lib/cf-named-tunnel.sh destroy <name> <hostname>)"