Phase 5: import mint-ensemble-manager into the single repository

.claude/skills/bump-image-tag/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: bump-image-tag
+description: Pin a MINT deployment to one commit of `mintproject/monorepo` by writing `global.imageTag` in a helm values file. Use when asked to deploy a monorepo branch or release, bump helm image tags, or refresh a values file to the latest images.
+---
+
+# bump-image-tag
+
+One single-repo commit builds all four services, so **one tag names the whole system state**. This skill writes that one tag.
+
+```bash
+.claude/skills/bump-image-tag/bump.sh --values <path> [--branch NAME | --tag TAG] [--pr] [--dry-run]
+```
+
+`--help` lists every flag. Start with `--dry-run`.
+
+## What it writes
+
+| | |
+|---|---|
+| `.global.imageTag` | the resolved tag |
+| `.components.<key>.image.tag` | emptied, for the four services below |
+
+The chart resolves `.image.tag | default .Values.global.imageTag | default .Chart.AppVersion`, so **a per-service tag wins over the global**. The chart's own defaults pin all four, which is why the script clears them. Leaving one set is the silent failure this skill exists to remove: the deploy reports success and runs the old image.
+
+The four services that come from `mintproject/monorepo`:
+
+| Component key | Image |
+|---|---|
+| `hasura` | `ghcr.io/mintproject/graphql-engine` |
+| `model_catalog_api` | `ghcr.io/mintproject/model-catalog-api` |
+| `ui_react` | `ghcr.io/mintproject/mint-ui-react` |
+| `ensemble_manager` | `ghcr.io/mintproject/ensemble-manager` |
+
+`ui` (mint-ui-lit) is still its own repository. The script never touches it, nor `cromo`, `mic_*`, `data_catalog*`, `model_catalog_endpoint`, `hasura_db` or the auth webhook.
+
+## Where globals live
+
+Helm reads globals only from the **root** `global` key, even when MINT is a subchart. Components move with the subchart; globals do not. So a values file that wraps the chart holds `MINT.components.*` beside a root-level `global.imageTag`. The script detects which root applies and prints it.
+
+## Two aborts, both deliberate
+
+- **A repository that is not the GHCR one.** A tag from `mintproject/monorepo` does not exist on Docker Hub. Fix the chart before pinning.
+- **An image missing at that tag.** Every one of the four must be in GHCR before the pin is real. Wait for CI. `--skip-image-check` overrides, for a tag you know is still building.
+
+Chart `9.0.0-beta.7` or newer. Earlier charts have no `global.imageTag`, so the write is inert.
+
+## Where this fits
+
+1. Push the branch, wait for CI (`gh pr checks <n>`).
+2. Verify the change is live on the dev cluster — the `test-on-k8s-dev` skill.
+3. Pin the tag and open the PR (this skill).

.claude/skills/bump-image-tag/bump.sh

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# Pin one MINT release to a values file by writing global.imageTag.
+# See SKILL.md.
+set -euo pipefail
+
+SOURCE_REPO="mintproject/monorepo"
+
+# chart component key|GHCR repository
+SERVICES=(
+  "hasura|ghcr.io/mintproject/graphql-engine"
+  "model_catalog_api|ghcr.io/mintproject/model-catalog-api"
+  "ui_react|ghcr.io/mintproject/mint-ui-react"
+  "ensemble_manager|ghcr.io/mintproject/ensemble-manager"
+)
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") --values PATH [options]
+
+Required:
+  --values PATH        Values file to edit.
+
+Tag selection (pick one; default is the current branch of this working tree):
+  --branch NAME        Resolve the head SHA of NAME in ${SOURCE_REPO}.
+  --tag TAG            Use TAG verbatim. For a release version, e.g. v9.1.0.
+
+Options:
+  --base NAME          Pull request base. Default: main
+  --pr                 Commit, push and open a pull request.
+  --skip-image-check   Write the tag before the images exist.
+  --dry-run            Print the plan and exit.
+  -h, --help
+EOF
+}
+
+VALUES=""
+BRANCH=""
+TAG=""
+BASE="main"
+OPEN_PR=0
+SKIP_IMAGE_CHECK=0
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --values)            VALUES="$2"; shift 2 ;;
+    --branch)            BRANCH="$2"; shift 2 ;;
+    --tag)               TAG="$2"; shift 2 ;;
+    --base)              BASE="$2"; shift 2 ;;
+    --pr)                OPEN_PR=1; shift ;;
+    --skip-image-check)  SKIP_IMAGE_CHECK=1; shift ;;
+    --dry-run)           DRY_RUN=1; shift ;;
+    -h|--help)           usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$VALUES" ]] || { echo "ERROR: --values is required" >&2; usage >&2; exit 2; }
+[[ -f "$VALUES" ]] || { echo "ERROR: no such file: $VALUES" >&2; exit 1; }
+[[ -n "$BRANCH" && -n "$TAG" ]] && { echo "ERROR: --branch and --tag are exclusive" >&2; exit 2; }
+
+command -v yq   >/dev/null || { echo "yq not found (mikefarah v4)" >&2; exit 1; }
+command -v curl >/dev/null || { echo "curl not found" >&2; exit 1; }
+
+# ---------------------------------------------------------------- resolve tag
+if [[ -z "$TAG" ]]; then
+  [[ -n "$BRANCH" ]] || BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+  TAG="$(git ls-remote "https://github.com/${SOURCE_REPO}.git" "refs/heads/${BRANCH}" | cut -f1)"
+  [[ -n "$TAG" ]] || { echo "ERROR: ${SOURCE_REPO} has no branch ${BRANCH}" >&2; exit 1; }
+  echo "resolved ${SOURCE_REPO}@${BRANCH} -> ${TAG}"
+else
+  echo "using tag ${TAG} verbatim"
+fi
+
+# --------------------------------------------------- locate the components root
+# Helm reads globals only from the root `global` key, even when the chart is a
+# subchart. Components move with the subchart; globals do not.
+if [[ "$(yq '.MINT.components // "null"' "$VALUES")" != "null" ]]; then
+  COMPONENTS=".MINT.components"
+elif [[ "$(yq '.components // "null"' "$VALUES")" != "null" ]]; then
+  COMPONENTS=".components"
+else
+  echo "ERROR: ${VALUES} has neither .components nor .MINT.components" >&2
+  exit 1
+fi
+echo "components root: ${COMPONENTS}"
+
+# ------------------------------------------------------- check the repositories
+FAIL=0
+for entry in "${SERVICES[@]}"; do
+  key="${entry%%|*}"
+  want="${entry##*|}"
+  have="$(yq "${COMPONENTS}.${key}.image.repository // \"\"" "$VALUES")"
+  [[ -z "$have" ]] && continue
+  if [[ "$have" != "$want" ]]; then
+    echo "ERROR: ${COMPONENTS}.${key}.image.repository is ${have}, not ${want}" >&2
+    echo "       A tag from ${SOURCE_REPO} does not exist there." >&2
+    FAIL=1
+  fi
+done
+[[ $FAIL -eq 0 ]] || { echo "Fix the repositories in the chart first." >&2; exit 1; }
+
+# ------------------------------------------------------------- check the images
+if [[ $SKIP_IMAGE_CHECK -eq 0 ]]; then
+  for entry in "${SERVICES[@]}"; do
+    repo="${entry##*|}"
+    path="${repo#ghcr.io/}"
+    # A package that does not exist yet refuses the token. Report that as a
+    # missing image, rather than aborting on curl's exit status.
+    token="$(curl -sS "https://ghcr.io/token?scope=repository:${path}:pull&service=ghcr.io" \
+      | yq -p json '.token // ""' 2>/dev/null || true)"
+    if [[ -z "$token" ]]; then
+      echo "MISSING ${repo}:${TAG} (no anonymous pull token; the package is private or absent)" >&2
+      FAIL=1
+      continue
+    fi
+    code="$(curl -s -o /dev/null -w '%{http_code}' \
+      -H "Authorization: Bearer ${token}" \
+      -H 'Accept: application/vnd.oci.image.index.v1+json' \
+      -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
+      "https://ghcr.io/v2/${path}/manifests/${TAG}")"
+    if [[ "$code" == "200" ]]; then
+      echo "ok      ${repo}:${TAG}"
+    else
+      echo "MISSING ${repo}:${TAG} (HTTP ${code})" >&2
+      FAIL=1
+    fi
+  done
+  [[ $FAIL -eq 0 ]] || {
+    echo "Wait for CI, or pass --skip-image-check." >&2
+    exit 1
+  }
+fi
+
+# ---------------------------------------------------------------------- the plan
+OLD="$(yq '.global.imageTag // ""' "$VALUES")"
+echo
+echo "plan for ${VALUES}:"
+echo "  .global.imageTag: '${OLD}' -> '${TAG}'"
+PINNED=()
+for entry in "${SERVICES[@]}"; do
+  key="${entry%%|*}"
+  have="$(yq "${COMPONENTS}.${key}.image.tag // \"\"" "$VALUES")"
+  if [[ -n "$have" ]]; then
+    PINNED+=("$key")
+    echo "  ${COMPONENTS}.${key}.image.tag: '${have}' -> '' (a per-service tag wins over the global)"
+  fi
+done
+
+[[ $DRY_RUN -eq 1 ]] && { echo; echo "dry run: nothing written"; exit 0; }
+
+# ---------------------------------------------------------------------- write
+yq -i ".global.imageTag = \"${TAG}\"" "$VALUES"
+for key in "${PINNED[@]:-}"; do
+  [[ -n "$key" ]] || continue
+  yq -i "${COMPONENTS}.${key}.image.tag = \"\"" "$VALUES"
+done
+echo
+echo "wrote ${VALUES}"
+
+[[ $OPEN_PR -eq 1 ]] || { echo "Review with: git -C \"\$(dirname ${VALUES})\" diff"; exit 0; }
+
+# ------------------------------------------------------------- commit, push, PR
+command -v gh >/dev/null || { echo "gh not found; the file is written, open the PR by hand" >&2; exit 1; }
+TOP="$(git -C "$(dirname "$VALUES")" rev-parse --show-toplevel)"
+SHORT="${TAG:0:12}"
+PR_BRANCH="bump/imagetag-${SHORT}"
+SUBJECT="chore: pin global.imageTag to ${SHORT}"
+BODY="Pins every image the chart takes from \`${SOURCE_REPO}\` to \`${TAG}\`.
+
+One single-repo commit builds all four services, so one tag names the whole
+system state. Per-service tags are cleared, because they win over the global."
+
+# Branch off the base the pull request targets, or the diff carries whatever
+# else the current branch holds.
+ON="$(git -C "$TOP" rev-parse --abbrev-ref HEAD)"
+if [[ "$ON" != "$BASE" ]]; then
+  echo "ERROR: $(basename "$TOP") is on '${ON}', not '${BASE}'." >&2
+  echo "       The file is written. Check it out on ${BASE} and rerun, or commit by hand." >&2
+  exit 1
+fi
+
+ABS="$(cd "$(dirname "$VALUES")" && pwd)/$(basename "$VALUES")"
+git -C "$TOP" checkout -B "$PR_BRANCH" >/dev/null
+git -C "$TOP" add "$ABS"
+git -C "$TOP" commit -m "$SUBJECT" -m "$BODY"
+git -C "$TOP" push -u origin "$PR_BRANCH"
+( cd "$TOP" && gh pr create --base "$BASE" --head "$PR_BRANCH" --title "$SUBJECT" --body "$BODY" )

.claude/skills/test-on-k8s-dev/SKILL.md

@@ -1,36 +1,40 @@
 ---
 name: test-on-k8s-dev
-description: Deploy and test a submodule branch build on the shared MicroK8s development cluster (release `mint`, namespace `mint`) before opening a helm PR. Use when asked to test a change on Kubernetes, verify a fix on the dev instance, check whether a deployed image actually contains a change, or reach Hasura / the model catalog API running in-cluster.
+description: Deploy and test a `mintproject/monorepo` branch build on the shared MicroK8s development cluster (release `mint`, namespace `mint`) before pinning a tag. Use when asked to test a change on Kubernetes, verify a fix on the dev instance, check whether a deployed image actually contains a change, or reach Hasura / the model catalog API running in-cluster.
 ---
 
 # test-on-k8s-dev
 
-How to exercise a change on the shared MicroK8s dev cluster. This is the gap between "CI is green" and "open a helm PR": CI proves the image builds, this proves it works against real data.
+How to exercise a change on the shared MicroK8s dev cluster. This is the gap between "CI is green" and "pin the tag": CI proves the image builds, this proves it works against real data.
 
 For local-only work use the `run-e2e-hasura` skill in `model-catalog-api/` instead. That runs against a local Hasura and needs no cluster.
 
 ## The cluster
 
-Verified 2026-08-27:
+Verified 2026-08-30:
 
 | | |
 |---|---|
 | kubectl context | `microk8s` (cluster `microk8s-cluster`, node `pop-os`, k8s v1.31.14) |
 | Namespace | `mint` (already the context default) |
-| Helm release | `mint`, chart `MINT-9.0.0-beta.2` |
+| Helm release | `mint`, chart `MINT-9.0.0-beta.6` |
 
 The cluster is remote, not on the laptop. `kubectl get nodes` is the fastest liveness check.
 
 **Two stale names to ignore.** `helm-charts/README.md` documents installing the release as `testing-mint`, and `model-catalog-api/src/hasura/client.ts` defaults `HASURA_GRAPHQL_URL` to `http://testing-mint-hasura.mint.svc.cluster.local/v1/graphql`. Neither matches this cluster, where the release is `mint` and the in-cluster URL is `http://mint-hasura/v1/graphql`. Resource names are `mint-*`, not `testing-mint-*`.
 
 ## Component map
 
-| Submodule | Deployment | Container | Service | Ingress host | Chart values key |
-|---|---|---|---|---|---|
-| `model-catalog-api` | `mint-model-catalog` | `model-catalog` | `mint-model-catalog:80` | `api.models.mint.local` | `components.model_catalog_api.image.tag` |
-| `graphql_engine` | `mint-hasura` | | `mint-hasura:80` | `graphql.mint.local` | `components.hasura.image.tag` |
-| `mint-ensemble-manager` | `mint-ensemble-manager` | | | `ensemble-manager.mint.local` | `components.ensemble_manager.image.tag` |
-| `ui` (mint-ui-lit) | `mint-ui` | | | `mint.local` | `components.ui.image.tag` |
+The four services that ship from `mintproject/monorepo`:
+
+| Directory | Deployment | Container | Ingress host | Image |
+|---|---|---|---|---|
+| `model-catalog-api` | `mint-model-catalog` | `model-catalog` | `api.models.mint.local` | `ghcr.io/mintproject/model-catalog-api` |
+| `graphql_engine` | `mint-hasura` | `hasura` | `graphql.mint.local` | `ghcr.io/mintproject/graphql-engine` |
+| `mint-ensemble-manager` | `mint-ensemble-manager` | `head` | `ensemble-manager.mint.local` | `ghcr.io/mintproject/ensemble-manager` |
+| `ui-react` | `mint-ui-react` | `ui-react` | `mint.local` | `ghcr.io/mintproject/mint-ui-react` |
+
+`ui` (mint-ui-lit) is still its own repository: deployment `mint-ui`, host `legacy.mint.local`.
 
 The `*.mint.local` hosts only resolve if the node IP is in your `/etc/hosts`. Port-forwarding avoids that entirely and is the better default for a quick check.
 
@@ -47,23 +51,25 @@ Read-only, safe on a shared cluster, and enough to characterise current behaviou
 
 ## Deploying a branch build
 
-CI in `model-catalog-api` pushes on **every branch push**, so a branch image exists as soon as `build-and-push` is green — you do not need to merge to test:
+CI in `mintproject/monorepo` builds **all four services on every branch push**, with no path filter, so one commit gives you a whole consistent system. A branch image exists as soon as its `publish` job is green — you do not need to merge to test:
 
-- `ghcr.io/mintproject/model-catalog-api:<full-commit-sha>`
-- `ghcr.io/mintproject/model-catalog-api:<branch-name-with-slashes-as-dashes>`
-- `:latest` is only republished on `main`.
+- `ghcr.io/mintproject/<image>:<full-commit-sha>`
+- `ghcr.io/mintproject/<image>:<branch-name-with-slashes-as-dashes>`
+- `:latest` is only republished on the default branch.
 
 Confirm the image is really in the registry before deploying it:
 
 ```bash
-TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:mintproject/model-catalog-api:pull&service=ghcr.io" \
+IMAGE=model-catalog-api
+SHA=<full-sha>
+TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:mintproject/${IMAGE}:pull&service=ghcr.io" \
   | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
 curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" \
   -H "Accept: application/vnd.oci.image.index.v1+json" \
-  "https://ghcr.io/v2/mintproject/model-catalog-api/manifests/<sha>"
+  "https://ghcr.io/v2/mintproject/${IMAGE}/manifests/${SHA}"
 ```
 
-`200` means present.
+`200` means present. Brace the variable as `${IMAGE}`. In zsh, `"$IMAGE:latest"` applies the `:l` lowercase modifier instead of appending a tag, and the probe silently reports the wrong thing.
 
 Then point the deployment at it. **This mutates a shared cluster — ask the user first.**
 
@@ -85,6 +91,8 @@ kubectl rollout undo -n mint deploy/mint-model-catalog
 
 Helm will also overwrite this on its next `helm upgrade`, so a forgotten `set image` is not permanent — but do not leave the shared instance on a branch build.
 
+**A helm upgrade does not run Hasura migrations.** The migration job is a post-install hook only, so a `graphql_engine` schema change needs a hand-run step ([#117](https://github.com/mintproject/monorepo/issues/117)).
+
 ## Verifying the change is actually live
 
 **A 200 with plausible data does not mean your change deployed.** `model-catalog-api` is a Fastify + `fastify-openapi-glue` service: AJV validates the querystring against the OpenAPI spec and **silently strips any query param the spec does not declare**. An unrecognised filter is dropped, the endpoint returns an unfiltered page, and the response looks fine.
@@ -124,4 +132,4 @@ Two corollaries when adding a query param to this API:
 1. Push the branch, wait for CI (`gh pr checks <n>`).
 2. Confirm the image is in GHCR.
 3. Deploy it here and verify differentially (this skill).
-4. Only then pin the SHA in helm and open the PR — via the `update-helm-image-tags` or `dynamo-bump-from-branch` skill.
+4. Only then pin the tag and open the PR — the `bump-image-tag` skill.

.github/dependabot.yml

@@ -0,0 +1,41 @@
+# Monthly, and every entry grouped. Dependabot groups within one ecosystem and
+# one directory, so this is four pull requests a month, not four per dependency.
+# Ungrouped weekly updates are what produced 8 open and 0 merged on mint-ui-lit.
+version: 2
+updates:
+  # The case for this file. mint-ensemble-manager arrived pinned to
+  # actions/checkout@v2 and docker/login-action@v1.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      github-actions:
+        patterns: ['*']
+
+  - package-ecosystem: npm
+    directory: /model-catalog-api
+    schedule:
+      interval: monthly
+    groups:
+      model-catalog-api:
+        patterns: ['*']
+
+  - package-ecosystem: npm
+    directory: /mint-ensemble-manager
+    schedule:
+      interval: monthly
+    groups:
+      mint-ensemble-manager:
+        patterns: ['*']
+
+  - package-ecosystem: npm
+    directory: /ui-react
+    schedule:
+      interval: monthly
+    groups:
+      ui-react:
+        patterns: ['*']
+
+  # graphql_engine has no package manifest. Its Dockerfile pins the Hasura
+  # base image by hand.