@memberjunction/cli 5.37.0 → 5.39.0

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/db-preflight.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Database connection preflight.
+ *
+ * Opens a real connection using the same settings `mj migrate` uses, runs a
+ * trivial query, and classifies any failure into an actionable result. The
+ * headline case: detecting a self-signed / untrusted TLS certificate and
+ * suggesting `DB_TRUST_SERVER_CERTIFICATE` for local instances — instead of the
+ * cryptic "self-signed certificate" error surfacing mid-migration.
+ *
+ * Lives in MJCLI (not the installer) because the SQL driver (`mssql`) ships
+ * here; the installer surfaces it through `mj migrate` / `--check-connection`.
+ *
+ * @module lib/db-preflight
+ */
+import type { MJConfig } from '../config.js';
+/** The subset of config a connection needs — keeps this independently testable. */
+export type DbConnectionConfig = Pick<MJConfig, 'dbPlatform' | 'dbHost' | 'dbPort' | 'dbDatabase' | 'codeGenLogin' | 'codeGenPassword' | 'dbEncrypt' | 'dbTrustServerCertificate'>;
+/** Why a preflight connection failed, ordered by how specifically we can advise. */
+export type DbPreflightReason = 'tls-untrusted-cert' | 'auth' | 'unreachable' | 'other';
+/**
+ * Outcome of a connection preflight. A flat shape (rather than a discriminated
+ * union) because this package compiles without `strictNullChecks`, so union
+ * narrowing on `Ok` is unreliable; `Reason`/`Message`/`Suggestion` are populated
+ * only when `Ok` is false.
+ */
+export interface DbPreflightResult {
+    /** True when a connection was established and a probe query succeeded. */
+    Ok: boolean;
+    /** Failure classification (set only when `Ok` is false). */
+    Reason?: DbPreflightReason;
+    /** Underlying error message (set only when `Ok` is false). */
+    Message?: string;
+    /** An actionable next step, when one can be offered. */
+    Suggestion?: string;
+}
+/**
+ * Open a real connection with the configured encrypt/trust settings, run a
+ * trivial query, and report success or a classified failure. Always closes the
+ * connection it opened.
+ */
+export declare function verifyDatabaseConnection(config: DbConnectionConfig): Promise<DbPreflightResult>;
+//# sourceMappingURL=db-preflight.d.ts.map

package/dist/lib/db-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-preflight.d.ts","sourceRoot":"","sources":["../../src/lib/db-preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,QAAQ,EACR,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,cAAc,GAAG,iBAAiB,GAAG,WAAW,GAAG,0BAA0B,CAClI,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,EAAE,EAAE,OAAO,CAAC;IACZ,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAiED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuBrG"}

package/dist/lib/db-preflight.js

@@ -0,0 +1,113 @@
+/**
+ * Database connection preflight.
+ *
+ * Opens a real connection using the same settings `mj migrate` uses, runs a
+ * trivial query, and classifies any failure into an actionable result. The
+ * headline case: detecting a self-signed / untrusted TLS certificate and
+ * suggesting `DB_TRUST_SERVER_CERTIFICATE` for local instances — instead of the
+ * cryptic "self-signed certificate" error surfacing mid-migration.
+ *
+ * Lives in MJCLI (not the installer) because the SQL driver (`mssql`) ships
+ * here; the installer surfaces it through `mj migrate` / `--check-connection`.
+ *
+ * @module lib/db-preflight
+ */
+import { openConnection } from '../baseline/connection.js';
+/** Map the config's DB platform to the connection helper's dialect. */
+function dialectFor(platform) {
+    return platform === 'postgresql' ? 'postgres' : 'mssql';
+}
+/** True when the error indicates an untrusted / self-signed TLS certificate. */
+function isUntrustedCertError(message) {
+    const m = message.toLowerCase();
+    return (m.includes('self-signed certificate') ||
+        m.includes('self signed certificate') ||
+        m.includes('depth_zero_self_signed_cert') ||
+        m.includes('self_signed_cert_in_chain') ||
+        m.includes('unable to verify the first certificate') ||
+        m.includes('unable to get local issuer certificate'));
+}
+/** True when the error indicates a credentials / login problem. */
+function isAuthError(message) {
+    const m = message.toLowerCase();
+    return m.includes('login failed') || m.includes('password authentication failed');
+}
+/** True when the error indicates the host / port could not be reached. */
+function isUnreachableError(message) {
+    const m = message.toLowerCase();
+    return (m.includes('econnrefused') || m.includes('etimedout') || m.includes('enotfound') || m.includes('connection timed out') || m.includes('could not connect'));
+}
+/** Turn a connection error message into a classified, actionable result. */
+function classifyFailure(message, config) {
+    if (isUntrustedCertError(message)) {
+        // Only suggest trusting the cert when we aren't already trusting it — otherwise
+        // the problem is a different cert issue and that advice would mislead.
+        const suggestion = config.dbTrustServerCertificate
+            ? undefined
+            : 'The database is presenting a self-signed / untrusted TLS certificate. For a local or ' +
+                'development instance, set DB_TRUST_SERVER_CERTIFICATE=1 in your .env (or ' +
+                'dbTrustServerCertificate: true in mj.config.cjs) to trust it, then retry.';
+        return { Ok: false, Reason: 'tls-untrusted-cert', Message: message, Suggestion: suggestion };
+    }
+    if (isAuthError(message)) {
+        return {
+            Ok: false,
+            Reason: 'auth',
+            Message: message,
+            Suggestion: 'Check the database login (codeGenLogin / codeGenPassword) in your .env or mj.config.cjs.',
+        };
+    }
+    if (isUnreachableError(message)) {
+        return {
+            Ok: false,
+            Reason: 'unreachable',
+            Message: message,
+            Suggestion: `Confirm the database is running and reachable at ${config.dbHost}:${config.dbPort}.`,
+        };
+    }
+    return { Ok: false, Reason: 'other', Message: message };
+}
+/**
+ * Open a real connection with the configured encrypt/trust settings, run a
+ * trivial query, and report success or a classified failure. Always closes the
+ * connection it opened.
+ */
+export async function verifyDatabaseConnection(config) {
+    const params = {
+        dialect: dialectFor(config.dbPlatform),
+        host: config.dbHost,
+        port: config.dbPort,
+        user: config.codeGenLogin,
+        password: config.codeGenPassword,
+        database: config.dbDatabase,
+        encrypt: config.dbEncrypt,
+        trustServerCertificate: config.dbTrustServerCertificate,
+    };
+    let conn;
+    try {
+        const runner = await openConnection(params);
+        conn = runner;
+        await runner.query('SELECT 1');
+        return { Ok: true };
+    }
+    catch (err) {
+        return classifyFailure(err instanceof Error ? err.message : String(err), config);
+    }
+    finally {
+        await closeQuietly(conn);
+    }
+}
+/** Best-effort close of a preflight connection; a teardown error must not mask the verdict. */
+async function closeQuietly(conn) {
+    if (!conn)
+        return;
+    try {
+        await conn.close();
+    }
+    catch (closeErr) {
+        // Intentionally ignored: this connection only probed reachability, so a close
+        // failure is not actionable and must not overwrite the preflight result.
+        void closeErr;
+    }
+}
+//# sourceMappingURL=db-preflight.js.map

package/dist/lib/db-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-preflight.js","sourceRoot":"","sources":["../../src/lib/db-preflight.ts"],"names":[],"mappings":"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"}