M6 (part 1): per-recipe meta + D4 recipe-local discovery + shared naming helper

Recipe-agnostic harness (no surgery to enroll a recipe): recipe_meta.py for
health path/codes/timeouts; run_recipe_local discovers + runs recipe-shipped
tests/ against the live app. install non-regressed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

JOURNAL.md

@@ -389,3 +389,23 @@ task briefly holds the volume), (4) **verifies** no residual services/volumes/se
 - Full 3-stage run (install/upgrade/backup) still green with verified teardown, no TeardownError.
 
 A2/A3 fixed; left for the Adversary to re-test + close.
+
+## 2026-05-27 — M6 (part 1): harness enhancements for recipe #2 + D4 discovery
+
+Before enrolling recipe #2, made the shared harness recipe-agnostic so enrolling a recipe needs no
+harness-code change (D5):
+- **Per-recipe meta** (`tests/<recipe>/recipe_meta.py`, optional): HEALTH_PATH, HEALTH_OK,
+  DEPLOY_TIMEOUT, HTTP_TIMEOUT. conftest reads it; `wait_healthy` gained a `path` param (e.g.
+  keycloak `/realms/master`). Defaults preserve custom-html behaviour (verified: install still green).
+- **Shared naming** (`harness/naming.py`): single source for the `<recipe[:4]>-<6hex>` domain, used
+  by conftest + the orchestrator.
+- **D4 recipe-local discovery** (`run_recipe_ci.run_recipe_local`): if a recipe ships `tests/` with
+  `test_*.py`, deploy the app, run those tests against the LIVE deployment (contract: env
+  `CCCI_BASE_URL` + `CCCI_APP_DOMAIN`), merge as another reported stage, guaranteed teardown. Real
+  recipes ship tests/ committed in their repo (clean checkout) → discovered on clone/fetch. (custom-
+  html via catalogue is an awkward case — abra refuses an unstaged recipe and `abra recipe fetch`
+  resets local commits — so D4 is demonstrated end-to-end with recipe #2 hedgedoc, which ships
+  committed tests/.)
+
+**Next:** mirror hedgedoc (postgres+hedgedoc, DB-backed) via the mirror+PR flow with a committed
+tests/ dir, write tests/hedgedoc/ (install/upgrade/backup + recipe_meta), run all stages + D4 green.

runner/harness/lifecycle.py

@@ -114,9 +114,10 @@ def http_get(domain: str, path: str = "/", timeout: int = 15) -> int:
         return 0
 
 
-def wait_healthy(domain: str, ok_codes=(200, 301, 302), deploy_timeout: int = 600,
-                 http_timeout: int = 300) -> None:
-    """Wait for stack services converged, then for the app to answer over HTTPS."""
+def wait_healthy(domain: str, ok_codes=(200, 301, 302), path: str = "/",
+                 deploy_timeout: int = 600, http_timeout: int = 300) -> None:
+    """Wait for stack services converged, then for the app to answer ok over HTTPS at `path`.
+    `path` is per-recipe (recipe_meta.HEALTH_PATH), e.g. keycloak uses /realms/master."""
     deadline = time.time() + deploy_timeout
     while time.time() < deadline:
         if services_converged(domain):
@@ -128,11 +129,11 @@ def wait_healthy(domain: str, ok_codes=(200, 301, 302), deploy_timeout: int = 60
     deadline = time.time() + http_timeout
     last = 0
     while time.time() < deadline:
-        last = http_get(domain)
+        last = http_get(domain, path)
         if last in ok_codes:
             return
         time.sleep(5)
-    raise TimeoutError(f"{domain}: not healthy over HTTPS (last status {last})")
+    raise TimeoutError(f"{domain}: not healthy over HTTPS {path} (last status {last})")
 
 
 def upgrade_app(domain: str, version: str | None = None) -> None:

runner/harness/naming.py

@@ -0,0 +1,20 @@
+"""Shared run-app domain naming (used by the conftest fixtures and the orchestrator).
+
+Domain = "<recipe[:4]>-<6hex(recipe|pr|ref)>.ci.commoninternet.net" — short enough for Docker's
+64-char swarm config/secret name limit, unique per run, collision-safe across recipes (DECISIONS.md).
+"""
+from __future__ import annotations
+
+import hashlib
+import time
+
+
+def _short(s: str, n: int = 8) -> str:
+    return "".join(c for c in s if c.isalnum())[:n] or "local"
+
+
+def app_domain(recipe: str, pr: str = "0", ref: str | None = None) -> str:
+    ref = ref or ("local" + str(int(time.time())))
+    tag = _short(recipe, 4).lower()
+    h = hashlib.sha1(f"{recipe}|{pr}|{ref}".encode()).hexdigest()[:6]
+    return f"{tag}-{h}.ci.commoninternet.net"

runner/run_recipe_ci.py

@@ -16,11 +16,14 @@ Run env (python with pytest+playwright, PLAYWRIGHT_BROWSERS_PATH) is provided by
 """
 from __future__ import annotations
 
+import glob
 import os
 import subprocess
 import sys
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(ROOT, "runner"))
+from harness import lifecycle, naming  # noqa: E402
 STAGE_FILES = {
     "install": "test_install.py",
     "upgrade": "test_upgrade.py",
@@ -73,11 +76,37 @@ def main() -> int:
         ran += 1
         if rc != 0:
             overall = rc
+    # D4: recipe-local tests. If the recipe repo ships a tests/ dir, deploy the app and run those
+    # tests against the LIVE deployment (contract: CCCI_BASE_URL + CCCI_APP_DOMAIN env), merging the
+    # result into this run as another reported stage. Teardown is guaranteed.
+    rc = run_recipe_local(recipe)
+    if rc is not None:
+        ran += 1
+        if rc != 0:
+            overall = rc
+
     if ran == 0:
         print("no stage test files found", file=sys.stderr)
         return 1
     return overall
 
 
+def run_recipe_local(recipe: str) -> int | None:
+    local_dir = os.path.expanduser(f"~/.abra/recipes/{recipe}/tests")
+    if not os.path.isdir(local_dir) or not glob.glob(os.path.join(local_dir, "test_*.py")):
+        return None  # recipe ships no tests/ — D4 is a no-op for it
+    print("\n===== STAGE: recipe-local (D4) =====", flush=True)
+    domain = naming.app_domain(recipe, os.environ.get("PR", "0"), os.environ.get("REF"))
+    lifecycle.janitor()
+    try:
+        lifecycle.deploy_app(recipe, domain, version=os.environ.get("VERSION") or None)
+        lifecycle.wait_healthy(domain)
+        env = dict(os.environ, CCCI_APP_DOMAIN=domain, CCCI_BASE_URL=f"https://{domain}")
+        return subprocess.call([sys.executable, "-m", "pytest", "-v", "-rA", local_dir],
+                               cwd=ROOT, env=env)
+    finally:
+        lifecycle.teardown_app(domain, verify=False)
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

tests/conftest.py

@@ -6,21 +6,36 @@ computes a unique app domain per run so concurrent runs never collide, and GUARA
 """
 from __future__ import annotations
 
-import hashlib
 import os
 import sys
-import time
 
 import pytest
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "runner"))
-from harness import lifecycle  # noqa: E402
+from harness import lifecycle, naming  # noqa: E402
 
 
 def _short(s: str, n: int = 8) -> str:
     return "".join(c for c in s if c.isalnum())[:n] or "local"
 
 
+def _recipe_meta(recipe: str) -> dict:
+    """Optional per-recipe config so enrolling a recipe needs NO shared-harness change (D5).
+    A recipe may ship tests/<recipe>/recipe_meta.py with any of: HEALTH_PATH (str),
+    HEALTH_OK (tuple of status codes), DEPLOY_TIMEOUT (int), HTTP_TIMEOUT (int)."""
+    path = os.path.join(os.path.dirname(__file__), recipe, "recipe_meta.py")
+    meta = {"HEALTH_PATH": "/", "HEALTH_OK": (200, 301, 302),
+            "DEPLOY_TIMEOUT": 600, "HTTP_TIMEOUT": 300}
+    if os.path.exists(path):
+        ns: dict = {}
+        with open(path) as fh:
+            exec(compile(fh.read(), path, "exec"), ns)  # noqa: S102 (trusted, in-repo)
+        for k in meta:
+            if k in ns:
+                meta[k] = ns[k]
+    return meta
+
+
 @pytest.fixture(scope="session")
 def recipe() -> str:
     return os.environ.get("RECIPE", "custom-html")
@@ -33,33 +48,39 @@ def app_domain(recipe) -> str:
     # subdomain label must stay short. Use <recipe[:4]>-<6hex(recipe|pr|ref)> — unique per run,
     # collision-safe across recipes (full recipe in the hash), readable context lives in the
     # Drone build params + PR comment. (Deviation from plan §4.0 long name; see DECISIONS.md.)
-    pr = os.environ.get("PR", "0")
-    ref = os.environ.get("REF", "local" + str(int(time.time())))
-    tag = _short(recipe, 4).lower()
-    h = hashlib.sha1(f"{recipe}|{pr}|{ref}".encode()).hexdigest()[:6]
-    return f"{tag}-{h}.ci.commoninternet.net"
+    return naming.app_domain(recipe, os.environ.get("PR", "0"), os.environ.get("REF"))
+
+
+@pytest.fixture(scope="session")
+def meta(recipe) -> dict:
+    return _recipe_meta(recipe)
+
+
+def _wait_healthy(domain, meta):
+    lifecycle.wait_healthy(domain, ok_codes=tuple(meta["HEALTH_OK"]), path=meta["HEALTH_PATH"],
+                           deploy_timeout=meta["DEPLOY_TIMEOUT"], http_timeout=meta["HTTP_TIMEOUT"])
 
 
 @pytest.fixture
-def deployed(recipe, app_domain, request):
+def deployed(recipe, app_domain, meta, request):
     """Function-scoped: deploy the current/$REF version healthy, guaranteed teardown after.
     Used by stages that start from current (install/backup)."""
     version = os.environ.get("VERSION") or None
     lifecycle.janitor()
     request.addfinalizer(lambda: lifecycle.teardown_app(app_domain))
     lifecycle.deploy_app(recipe, app_domain, version=version)
-    lifecycle.wait_healthy(app_domain)
+    _wait_healthy(app_domain, meta)
     return app_domain
 
 
 @pytest.fixture(scope="session")
-def deployed_app(recipe, app_domain):
+def deployed_app(recipe, app_domain, meta):
     """Install stage: deploy the recipe and wait until healthy; tear down at session end."""
     version = os.environ.get("VERSION") or None
     lifecycle.janitor()  # sweep orphans from crashed runs first
     try:
         lifecycle.deploy_app(recipe, app_domain, version=version, secrets=True)
-        lifecycle.wait_healthy(app_domain)
+        _wait_healthy(app_domain, meta)
         yield app_domain
     finally:
         lifecycle.teardown_app(app_domain)