@memberjunction/cli 5.37.0 → 5.38.0

package/dist/init-templates/github-actions/regression.yml

@@ -0,0 +1,52 @@
+# Copy-paste GitHub Actions workflow to run the MJ regression suite against
+# YOUR app/instance using the published agentic-test-runner image — no MJ
+# monorepo checkout required.
+#
+# Setup:
+#   1. Drop this file in your repo at .github/workflows/regression.yml
+#   2. Add a target.json + metadata/ (tests + test-suites) to your repo (see
+#      `mj test regression init remote-mj` or the examples/ directory).
+#   3. Add repo secrets: AI_VENDOR_API_KEY__GeminiLLM (primary; and/or
+#      __AnthropicLLM), DB_HOST/DB_DATABASE/DB_USERNAME/DB_PASSWORD (a reachable
+#      MJ provider DB), and any auth env: refs your target.json uses
+#      (e.g. STAGING_TEST_USER / STAGING_TEST_PASSWORD).
+#
+# Pin IMAGE to the MJ version your instance runs.
+name: regression
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 7 * * *'   # nightly
+
+env:
+  IMAGE: memberjunction/agentic-test-runner:latest   # pin to :v<MJ-version>
+
+jobs:
+  regression:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run regression suite
+        run: |
+          docker run --rm \
+            -e DB_HOST="${{ secrets.DB_HOST }}" \
+            -e DB_DATABASE="${{ secrets.DB_DATABASE }}" \
+            -e DB_USERNAME="${{ secrets.DB_USERNAME }}" \
+            -e DB_PASSWORD="${{ secrets.DB_PASSWORD }}" \
+            -e DB_TRUST_SERVER_CERTIFICATE=true \
+            -e AI_VENDOR_API_KEY__GeminiLLM="${{ secrets.AI_VENDOR_API_KEY__GeminiLLM }}" \
+            -e AI_VENDOR_API_KEY__AnthropicLLM="${{ secrets.AI_VENDOR_API_KEY__AnthropicLLM }}" \
+            -e STAGING_TEST_USER="${{ secrets.STAGING_TEST_USER }}" \
+            -e STAGING_TEST_PASSWORD="${{ secrets.STAGING_TEST_PASSWORD }}" \
+            -v "${{ github.workspace }}/my-suite:/work:ro" \
+            -v "${{ github.workspace }}/test-results:/app/test-results" \
+            "$IMAGE" run --target=/work/target.json
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: regression-results
+          path: test-results/

package/dist/init-templates/remote-mj/README.md

@@ -0,0 +1,95 @@
+# Remote MJ — Mode B Reference
+
+Target profile for driving the **canonical MJ Explorer Regression Suite** (the
+25 tests baked into the MJ monorepo) against a **remote MJ Explorer
+deployment** — staging, customer, production. No app code lives here; this
+example is purely a target-profile + archive-config recipe.
+
+## When to use this
+
+You have a deployed MJ Explorer instance (not the local docker stack) and want
+to run the same regression coverage against it that the MJ team runs against
+`next`. Use cases:
+
+- Nightly health-check of a staging deployment.
+- Pre-release smoke test of a customer instance.
+- Validating a behavioral fix landed on production after a hotfix.
+
+If you need to test a **non-MJ app**, see [`../generic-web/`](../generic-web/)
+or [`../bring-your-own-app/`](../bring-your-own-app/) instead.
+
+## Layout
+
+```
+remote-mj/
+├── README.md                       # this file
+└── target.json                     # target profile (kind: mj-explorer)
+```
+
+No tests/, no oracles/, no metadata/ — this example reuses the canonical MJ
+suite that ships in `metadata/test-suites/.regression-suite.json` and the 25
+test JSONs in `metadata/tests/regression/`.
+
+## Running it (inside the MJ monorepo)
+
+```bash
+# 1. Copy + edit the target profile
+cp docker/regression/examples/remote-mj/target.json docker/regression/targets/staging.target.json
+# Edit URL, allowedDomains, env: refs to match your deployment
+
+# 2. Export the credentials referenced via env:
+export REMOTE_MJ_TEST_USER=qa@example.com
+export REMOTE_MJ_TEST_PASSWORD=...
+
+# 3. Run
+mj test regression remote --target=staging
+```
+
+Behind the scenes:
+
+1. The CLI loads `staging.target.json`, resolves `env:` refs, and exports
+   `MJ_TEST_VAR_baseUrl`, `MJ_TEST_VAR_allowedDomains`, `MJ_TEST_VAR_authUsername`,
+   `MJ_TEST_VAR_authPassword`, etc.
+2. Compose brings up the **full** profile so the runner has the local
+   ephemeral DB for result recording (MJExplorer + MJAPI also boot but are
+   unused — the runner targets the remote URL instead).
+3. The runner pushes test metadata to the ephemeral DB, then invokes
+   `mj test suite --name "MJ Explorer Regression Suite"`.
+4. Reports land in `docker/regression/test-results/run-{TIMESTAMP}/`.
+5. If the `ARCHIVE_DB_*` env vars are set, the suite run + children are
+   pulled to a JSON folder and pushed to the destination MJ via `mj sync`.
+
+## ⚠️ Prerequisite — variable substitution
+
+For Mode B to actually retarget the canonical MJ suite, the 25 test JSONs in
+`metadata/tests/regression/` need to use `{{baseUrl}}` / `{{authUsername}}` /
+`{{authPassword}}` / `{{allowedDomains}}` placeholders instead of hardcoded
+`http://localhost:4200`. This was Phase 1A's deliverable; the substitution
+**code** ships and is fully tested, but the **JSON conversion** is a follow-up
+(tracked in [`docker/regression/LIMITATIONS.md`](../../LIMITATIONS.md)).
+
+Until the conversion lands, this example sets up the plumbing correctly but
+the runner will still attempt `http://localhost:4200` — useful for archive
+flow + auth-flow testing, not yet for actual remote regression coverage.
+
+## Running it externally (outside the monorepo, via the published image)
+
+Once `memberjunction/agentic-test-runner:vX` is published:
+
+```bash
+# Scaffold the directory
+docker run --rm -v $(pwd):/out memberjunction/agentic-test-runner init remote-mj
+
+# Edit ./remote-mj/target.json, then run
+export REMOTE_MJ_TEST_USER=qa@example.com
+export REMOTE_MJ_TEST_PASSWORD=...
+
+docker run --rm \
+    -v $(pwd)/test-results:/app/test-results \
+    -e MJ_TEST_VAR_baseUrl="https://mj.example.com" \
+    -e MJ_TEST_VAR_allowedDomains='["mj.example.com","*.auth0.com"]' \
+    -e MJ_TEST_VAR_authUsername="$REMOTE_MJ_TEST_USER" \
+    -e MJ_TEST_VAR_authPassword="$REMOTE_MJ_TEST_PASSWORD" \
+    -e TEST_SUITE_NAME="MJ Explorer Regression Suite" \
+    memberjunction/agentic-test-runner
+```

package/dist/init-templates/remote-mj/target.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0",
+  "name": "remote-mj",
+  "kind": "mj-explorer",
+  "description": "Mode B reference target: drives the canonical MJ Explorer Regression Suite against a remote MJ Explorer deployment. Replace the URL + auth refs with your own values before running.",
+
+  "baseUrl": "https://mj.example.com",
+  "allowedDomains": ["mj.example.com", "*.auth0.com"],
+
+  "auth": {
+    "username": "env:REMOTE_MJ_TEST_USER",
+    "password": "env:REMOTE_MJ_TEST_PASSWORD",
+    "domains": ["mj.example.com", "*.auth0.com"]
+  },
+
+  "suite": "MJ Explorer Regression Suite",
+
+  "archive": {
+    "tag": "remote-mj-nightly",
+    "source": "remote-mj"
+  }
+}

package/dist/init-templates/static-file-server/Dockerfile

@@ -0,0 +1,23 @@
+# Mode D demo: bake a static HTML payload into nginx:alpine so the test-runner
+# can drive a tiny app that lives inside the regression compose network.
+#
+# This image is intentionally trivial — the whole point of the example is to
+# show the *overlay pattern*, not to teach app deployment. For a more realistic
+# Angular + Express + planted-bugs example, see ../bring-your-own-app/.
+FROM nginx:alpine
+
+# Tiny default config: serve /public on :3000, no caching so test re-runs
+# always see the latest HTML if the volume is bind-mounted.
+RUN printf '%s\n' \
+    'server {' \
+    '    listen 3000;' \
+    '    root /public;' \
+    '    index index.html;' \
+    '    add_header Cache-Control "no-store";' \
+    '    location / { try_files $uri $uri/ =404; }' \
+    '}' \
+    > /etc/nginx/conf.d/default.conf
+
+COPY public/ /public/
+
+EXPOSE 3000

package/dist/init-templates/static-file-server/README.md

@@ -0,0 +1,88 @@
+# Static File Server — Mode D Minimal Demo
+
+The smallest possible **Mode D** (Bring-Your-Own-App) example. An `nginx:alpine`
+container serving two HTML pages, brought up alongside the regression
+test-runner via a docker-compose overlay. Two trivial Computer Use tests
+verify the runner can reach the overlay-supplied service.
+
+Use this as the starting point when you want to test your own app inside the
+regression network without any framework assumptions. For a more realistic
+Angular + Express app with planted bugs, see [`../bring-your-own-app/`](../bring-your-own-app/).
+
+## Layout
+
+```
+static-file-server/
+├── README.md                                  # this file
+├── Dockerfile                                 # nginx:alpine + a custom server config
+├── docker-compose.app.yml                     # Mode D overlay (adds static-server service)
+├── target.json                                # target profile: kind=generic-web, baseUrl=http://static-server:3000
+├── public/
+│   ├── index.html                             # home page
+│   └── about.html                             # about page
+└── metadata/
+    ├── .mj-sync.json
+    ├── tests/
+    │   ├── .mj-sync.json
+    │   ├── .SS01-home-loads.json              # home-page smoke
+    │   └── .SS02-navigate-about.json          # nav-flow test
+    └── test-suites/
+        ├── .mj-sync.json
+        └── .static-server-suite.json
+```
+
+## Running it
+
+From the MJ monorepo root:
+
+```bash
+mj test regression remote \
+    --target=docker/regression/examples/static-file-server/target.json \
+    --overlay=docker/regression/examples/static-file-server/docker-compose.app.yml
+```
+
+What happens:
+
+1. **CLI loads the target** — exports `MJ_TEST_VAR_baseUrl=http://static-server:3000`,
+   `MJ_TEST_VAR_allowedDomains=["static-server"]`, `TEST_SUITE_NAME="Static Server Mode D Suite"`,
+   `EXTRA_METADATA_DIRS=/app/static-server-metadata`, and the remote-entrypoint dispatch.
+2. **Compose merges the overlay** — `docker compose -f base.yml -f overlay.yml --profile full up`.
+   The overlay adds the `static-server` service, makes it a test-runner dep
+   (`condition: service_healthy`), and mounts the test/suite metadata.
+3. **Stack boots in order** — SQL Server → migrations → MJAPI → MJExplorer → static-server →
+   test-runner. The MJ stack is up so the runner has an ephemeral DB for `TestRun` /
+   `TestRunOutput` rows; MJExplorer itself is unused in this run.
+4. **Runner pushes the metadata** — `mj sync push --dir=/app/static-server-metadata` adds
+   the two tests + suite to the DB.
+5. **Suite runs** — `mj test suite --name "Static Server Mode D Suite" --parallel`.
+   Each test navigates to `http://static-server:3000` (resolved via Docker's compose
+   DNS) and runs Computer Use against the HTML.
+6. **Reports** — markdown + HTML reports land in `docker/regression/test-results/run-{TIMESTAMP}/`.
+
+## What the overlay does
+
+[`docker-compose.app.yml`](docker-compose.app.yml) is a stack-extension overlay
+that compose merges with the base regression compose. It:
+
+- Defines a `static-server` service (build from this directory's `Dockerfile`).
+- Joins the `full` compose profile so it boots alongside the test-runner.
+- Adds a healthcheck so the runner waits for nginx to be ready.
+- Adds `static-server` to the test-runner's `depends_on`.
+- Mounts `metadata/` into the runner at `/app/static-server-metadata` (RW so
+  mj-sync can write back primary-key + sync state).
+
+Path note: compose resolves relative paths in overlays against the **first**
+`-f` file's directory (the base compose at `docker/regression/`), not against
+the overlay's own location. That's why the overlay references
+`examples/static-file-server/...` instead of `./...`.
+
+## Copying this example for your own app
+
+1. Copy the directory to `docker/regression/examples/my-app/` (or anywhere; mount it).
+2. Replace `Dockerfile` + `public/` (or whatever you serve) with your app's container.
+3. Edit `docker-compose.app.yml` — rename the service, adjust the healthcheck, add any
+   extra mounts/env-vars your app needs.
+4. Edit `target.json` — point `baseUrl` at your service hostname, list the hostname in
+   `allowedDomains`, rename the suite.
+5. Replace the test JSONs in `metadata/tests/` with goals specific to your app.
+6. Run with the same `mj test regression remote --target=... --overlay=...` command.

package/dist/init-templates/static-file-server/docker-compose.app.yml

@@ -0,0 +1,44 @@
+# Mode D overlay: boots the static-file-server alongside the test-runner so
+# the runner can reach it at http://static-server:3000 over the compose
+# network. Combine with the base regression compose:
+#
+#   mj test regression remote \
+#       --target=docker/regression/examples/static-file-server/target.json \
+#       --overlay=docker/regression/examples/static-file-server/docker-compose.app.yml
+#
+# What this overlay does:
+#   - Adds a `static-server` service (the app under test)
+#   - Mounts the example's test/suite metadata into the test-runner so the
+#     entrypoint can push them at run time
+#   - Adds `static-server` as a test-runner dependency so the runner waits
+#     for nginx to be ready
+
+services:
+  static-server:
+    # The base compose file is profile-gated. Mode D launches the test-runner
+    # via the `full` profile (so the local DB is available for results
+    # recording); join the same profile so this service starts alongside.
+    profiles: ["full"]
+    # Compose resolves relative paths in overlay files using the directory of
+    # the FIRST `-f` file (the base compose at docker/regression/), not the
+    # overlay's own location. Hence `examples/static-file-server` not `.`.
+    build:
+      context: examples/static-file-server
+      dockerfile: Dockerfile
+    image: mj-regression-static-server:latest
+    container_name: mj-regression-static-server
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O- http://localhost:3000/ > /dev/null"]
+      interval: 5s
+      timeout: 3s
+      retries: 6
+      start_period: 5s
+
+  test-runner:
+    depends_on:
+      static-server:
+        condition: service_healthy
+    volumes:
+      # Mode D test/suite metadata. RW because mj-sync writes primaryKey +
+      # sync state back into the JSON files after autoCreateMissingRecords.
+      - ./examples/static-file-server/metadata:/app/static-server-metadata

package/dist/init-templates/static-file-server/metadata/.mj-sync.json

@@ -0,0 +1,10 @@
+{
+  "version": "1.0.0",
+  "push": {
+    "autoCreateMissingRecords": true
+  },
+  "directoryOrder": [
+    "tests",
+    "test-suites"
+  ]
+}

package/dist/init-templates/static-file-server/metadata/test-suites/.mj-sync.json

@@ -0,0 +1,12 @@
+{
+  "entity": "MJ: Test Suites",
+  "filePattern": "**/.*.json",
+  "pull": {
+    "relatedEntities": {
+      "MJ: Test Suite Tests": {
+        "entity": "MJ: Test Suite Tests",
+        "foreignKey": "TestSuiteID"
+      }
+    }
+  }
+}

package/dist/init-templates/static-file-server/metadata/test-suites/.static-server-suite.json

@@ -0,0 +1,27 @@
+{
+  "fields": {
+    "Name": "Static Server Mode D Suite",
+    "Description": "Mode D reference suite — drives the regression runner against the static-file-server brought up by docker-compose.app.yml. Used as the minimal end-to-end demo of the overlay pattern.",
+    "Status": "Active"
+  },
+  "relatedEntities": {
+    "MJ: Test Suite Tests": [
+      {
+        "fields": {
+          "SuiteID": "@parent:ID",
+          "TestID": "@lookup:MJ: Tests.Name=SS01 - Static Server Home Loads",
+          "Sequence": 1,
+          "Status": "Active"
+        }
+      },
+      {
+        "fields": {
+          "SuiteID": "@parent:ID",
+          "TestID": "@lookup:MJ: Tests.Name=SS02 - Static Server Navigate About",
+          "Sequence": 2,
+          "Status": "Active"
+        }
+      }
+    ]
+  }
+}

package/dist/init-templates/static-file-server/metadata/tests/.SS01-home-loads.json

@@ -0,0 +1,45 @@
+{
+  "fields": {
+    "TypeID": "@lookup:MJ: Test Types.Name=Computer Use",
+    "Name": "SS01 - Static Server Home Loads",
+    "Description": "Mode D smoke: verifies the static-file-server's index page renders inside the regression network. Demonstrates that the test-runner can reach an overlay-supplied service via its compose hostname.",
+    "InputDefinition": {
+      "goal": "Verify the page loaded successfully. Look for a heading 'Mode D Demo', a paragraph mentioning the overlay pattern, and a navigation link to 'About'. Do not click anything.",
+      "startUrl": "{{baseUrl}}",
+      "allowedDomains": "{{allowedDomains}}",
+      "auth": { "bindings": [] }
+    },
+    "ExpectedOutcomes": {
+      "goalCompleted": true,
+      "finalUrlPattern": "^http://static-server:3000/?$",
+      "minConfidence": 0.7,
+      "maxSteps": 5,
+      "judgeValidationCriteria": [
+        "Page heading reads 'Mode D Demo'",
+        "Navigation includes a link to About",
+        "No browser error"
+      ]
+    },
+    "Configuration": {
+      "headless": true,
+      "maxSteps": 5,
+      "maxExecutionTime": 60000,
+      "screenshotHistoryDepth": 3,
+      "viewportWidth": 1024,
+      "viewportHeight": 600,
+      "controllerPromptName": "Computer Use - Controller",
+      "judgePromptName": "Computer Use - Judge",
+      "judgeFrequency": "EveryNSteps:2",
+      "oracles": [
+        { "type": "goal-completion", "weight": 0.7, "config": { "minConfidence": 0.7 } },
+        { "type": "url-match", "weight": 0.3, "config": { "pattern": "^http://static-server:3000/?$" } }
+      ],
+      "scoringWeights": {
+        "goal-completion": 0.7,
+        "url-match": 0.3
+      }
+    },
+    "Status": "Active",
+    "Tags": "P0,mode-d,static-server,smoke"
+  }
+}

package/dist/init-templates/static-file-server/metadata/tests/.SS02-navigate-about.json

@@ -0,0 +1,45 @@
+{
+  "fields": {
+    "TypeID": "@lookup:MJ: Test Types.Name=Computer Use",
+    "Name": "SS02 - Static Server Navigate About",
+    "Description": "Click the 'About' link in the static-server nav and verify the about page loads. Demonstrates a navigation flow against an overlay-supplied service.",
+    "InputDefinition": {
+      "goal": "Click the link labelled 'About' in the navigation. Verify the about page loads — it should display the heading 'About' and a link back to Home.",
+      "startUrl": "{{baseUrl}}",
+      "allowedDomains": "{{allowedDomains}}",
+      "auth": { "bindings": [] }
+    },
+    "ExpectedOutcomes": {
+      "goalCompleted": true,
+      "finalUrlPattern": "/about\\.html$",
+      "minConfidence": 0.7,
+      "maxSteps": 6,
+      "judgeValidationCriteria": [
+        "Final URL ends with /about.html",
+        "Page heading reads 'About'",
+        "A link back to Home is visible"
+      ]
+    },
+    "Configuration": {
+      "headless": true,
+      "maxSteps": 6,
+      "maxExecutionTime": 90000,
+      "screenshotHistoryDepth": 3,
+      "viewportWidth": 1024,
+      "viewportHeight": 600,
+      "controllerPromptName": "Computer Use - Controller",
+      "judgePromptName": "Computer Use - Judge",
+      "judgeFrequency": "EveryNSteps:2",
+      "oracles": [
+        { "type": "goal-completion", "weight": 0.6, "config": { "minConfidence": 0.7 } },
+        { "type": "url-match", "weight": 0.4, "config": { "pattern": "/about\\.html$" } }
+      ],
+      "scoringWeights": {
+        "goal-completion": 0.6,
+        "url-match": 0.4
+      }
+    },
+    "Status": "Active",
+    "Tags": "P1,mode-d,static-server,navigation"
+  }
+}

package/dist/init-templates/static-file-server/metadata/tests/.mj-sync.json

@@ -0,0 +1,12 @@
+{
+  "entity": "MJ: Tests",
+  "filePattern": "**/.*.json",
+  "pull": {
+    "lookupFields": {
+      "TypeID": {
+        "entity": "MJ: Test Types",
+        "field": "Name"
+      }
+    }
+  }
+}

package/dist/init-templates/static-file-server/public/about.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>About — Static File Server</title>
+</head>
+<body>
+    <h1>About</h1>
+    <p>This is the "about" page used by the Mode D demo's navigation test.</p>
+    <p><a href="/">← Home</a></p>
+</body>
+</html>

package/dist/init-templates/static-file-server/public/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>Static File Server — Mode D Demo</title>
+    <style>
+        body { font: 16px/1.5 system-ui, sans-serif; max-width: 640px; margin: 40px auto; padding: 0 16px; color: #222; }
+        h1 { color: #264FAF; }
+        nav { margin: 16px 0; }
+        nav a { margin-right: 12px; }
+        footer { margin-top: 40px; color: #888; font-size: 14px; }
+    </style>
+</head>
+<body>
+    <h1>Mode D Demo</h1>
+    <p>This static page is served by an nginx container that the regression test-runner
+    reaches via its compose-network hostname. The point of this example is to demonstrate
+    the docker-compose <em>overlay</em> pattern — bring your own app alongside the runner.</p>
+
+    <nav>
+        <a href="/">Home</a>
+        <a href="/about.html">About</a>
+    </nav>
+
+    <footer>Served by nginx:alpine inside the mj-regression compose network.</footer>
+</body>
+</html>

package/dist/init-templates/static-file-server/target.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "1.0",
+  "name": "static-server",
+  "kind": "generic-web",
+  "description": "Mode D demo: target the static-file-server container that the docker-compose.app.yml overlay brings up alongside the test-runner.",
+
+  "baseUrl": "http://static-server:3000",
+  "allowedDomains": ["static-server"],
+
+  "auth": { "bindings": [] },
+
+  "suite": "Static Server Mode D Suite",
+  "extraMetadataDirs": [
+    "/app/static-server-metadata"
+  ]
+}

package/dist/lib/regression/docker-helpers.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared helpers for `mj test regression *` subcommands.
+ *
+ * The CLI commands themselves are thin oclif wrappers — they just spawn
+ * `docker compose` / `bash` with the right flags. All the wiring (path
+ * resolution, profile selection, error reporting) lives here so the same
+ * conventions apply across every subcommand.
+ */
+import { type SpawnOptions } from 'node:child_process';
+export declare const REGRESSION_DIR = "docker/regression";
+export declare const COMPOSE_FILE = "docker/regression/docker-compose.test.yml";
+export declare const BACPAC_OVERLAY = "docker/regression/docker-compose.bacpac.yml";
+export declare const STANDALONE_COMPOSE = "docker/regression/docker-compose.standalone.yml";
+export declare const BACPAC_STANDALONE_COMPOSE = "docker/regression/docker-compose.bacpac-standalone.yml";
+/**
+ * Resolve a standalone compose file. Prefers the monorepo copy (cwd-relative
+ * `docker/regression/<name>`); falls back to the copy bundled into this CLI
+ * package at build time (`<pkg>/regression-compose/<name>`) so external users
+ * who only `npm i -g @memberjunction/cli` still have it. Returns the first path
+ * that exists, or the bundled path (so the caller can surface a clear error).
+ */
+export declare function resolveStandaloneCompose(monorepoRelPath: string): string;
+export declare const ENV_FILE = "docker/regression/.env.test";
+export declare const TARGETS_DIR = "docker/regression/targets";
+export declare const LOAD_TARGET_SCRIPT = "docker/regression/scripts/load-target-profile.cjs";
+export declare const GEN_FORMS_SCRIPT = "docker/regression/gen-forms.sh";
+export declare const RESULTS_DIR = "docker/regression/test-results";
+export declare const INLINE_REPORT_SCRIPT = "docker/regression/scripts/inline-report.cjs";
+/**
+ * The pinned runner image tag used when `init` (and future external invocations)
+ * shell out to `docker run memberjunction/agentic-test-runner …`. Kept here so
+ * a single bump updates every CLI command that consumes the image. The
+ * version is pinned to the most recent release that includes Phase 8.
+ */
+export declare const AGENTIC_TEST_RUNNER_IMAGE = "memberjunction/agentic-test-runner:latest";
+/**
+ * Verify the current working directory is the MJ monorepo root. If it isn't,
+ * print a helpful message and exit. Phase 4 still requires the user to be in
+ * the monorepo; Phase 8 will publish the docker image and lift this guard.
+ */
+export declare function requireMonorepoRoot(): void;
+/**
+ * Soft check — returns true when there's an MJ monorepo at-or-above cwd.
+ * Used by commands (compare, up, export, remote) to pick monorepo-relative
+ * paths over external/published-image paths. Unlike `requireMonorepoRoot()`,
+ * this does NOT exit on failure.
+ *
+ * The sentinel is the regression base compose file: it lives in every
+ * monorepo checkout and is never present in an external `npm i -g` install.
+ */
+export declare function isInsideMonorepo(startDir?: string): boolean;
+/** Returns true when `<cwd>/<ENV_FILE>` exists (e.g. user copied .env.test.example). */
+export declare function envFileExists(): boolean;
+/**
+ * Spawn a child process inheriting stdio. Resolves with the exit code.
+ * The promise NEVER rejects on a non-zero exit code — callers inspect the
+ * resolved number and propagate it to the user.
+ */
+export declare function spawnInherit(command: string, args: string[], options?: SpawnOptions): Promise<number>;
+/**
+ * Capture stdout from a child process (stderr inherited so errors surface).
+ * Resolves with { code, stdout }. Used by the remote subcommand to read the
+ * target-profile loader's JSON output without printing it to the user.
+ */
+export declare function spawnCapture(command: string, args: string[], options?: SpawnOptions): Promise<{
+    code: number;
+    stdout: string;
+}>;
+/**
+ * Build the base `docker compose -f <file> --env-file <file>` argument list.
+ * Optionally prepends a profile and additional overlay files (Mode D).
+ *
+ * Overlays are passed as additional `-f` flags AFTER the base compose file —
+ * compose merges them in order, so later overlays override earlier ones.
+ * Relative paths inside an overlay resolve against the FIRST `-f` file's
+ * directory (the base compose file at `docker/regression/`), NOT against the
+ * overlay's own location.
+ */
+export declare function dockerComposeArgs(profile?: string, extra?: string[], overlays?: string[]): string[];
+/**
+ * Resolve a target-profile argument to an absolute path. Accepts:
+ *   - "staging-mj"                  → docker/regression/targets/staging-mj.target.json
+ *   - "staging-mj.target.json"      → docker/regression/targets/staging-mj.target.json
+ *   - "./my/elsewhere.target.json"  → ./my/elsewhere.target.json (passthrough)
+ *   - absolute path                 → unchanged
+ */
+export declare function resolveTargetPath(input: string): string;
+/**
+ * Build a `docker run …` argument list for the published image (external,
+ * no-monorepo path). Mounts are [hostPath, containerPath] pairs; envFile is
+ * injected with `--env-file`; `host.docker.internal` is always mapped so a DB
+ * published on the host is reachable on Linux too.
+ */
+export declare function dockerRunArgs(image: string, subArgs: string[], opts?: {
+    mounts?: Array<[string, string]>;
+    envFile?: string;
+}): string[];
+//# sourceMappingURL=docker-helpers.d.ts.map

package/dist/lib/regression/docker-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/regression/docker-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D,eAAO,MAAM,cAAc,sBAAsB,CAAC;AAClD,eAAO,MAAM,YAAY,8CAA8C,CAAC;AACxE,eAAO,MAAM,cAAc,gDAAgD,CAAC;AAC5E,eAAO,MAAM,kBAAkB,oDAAoD,CAAC;AACpF,eAAO,MAAM,yBAAyB,2DAA2D,CAAC;AASlG;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAKxE;AACD,eAAO,MAAM,QAAQ,gCAAgC,CAAC;AACtD,eAAO,MAAM,WAAW,8BAA8B,CAAC;AACvD,eAAO,MAAM,kBAAkB,sDAAsD,CAAC;AACtF,eAAO,MAAM,gBAAgB,mCAAmC,CAAC;AACjE,eAAO,MAAM,WAAW,mCAAmC,CAAC;AAC5D,eAAO,MAAM,oBAAoB,gDAAgD,CAAC;AAElF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,8CAA8C,CAAC;AAErF;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAU1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAQ1E;AAED,wFAAwF;AACxF,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAiB3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,GAAE,MAAM,EAAO,EACpB,QAAQ,GAAE,MAAM,EAAO,GACtB,MAAM,EAAE,CAYV;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,MAAM,EAAE,CAUV"}