mmt-mcp 1.42.2-pre

package/dist/examples/professional/07_mock_server_timeout/test/slow_timeout_test.mmt

@@ -0,0 +1,15 @@
+type: test
+title: Mock server timeout simulation
+description: |-
+  Starts a mock server with a 3-second endpoint delay and calls it
+  with a 2-second request timeout.
+import:
+  server: ../server/mock_server.mmt
+  slow_request: ../api/slow_request.mmt
+steps:
+  - run: server
+  - call: slow_request
+    id: timeout_result
+    expect:
+      status: 200
+    report: all

package/dist/examples/professional/08_external_mtls_badssl/README.md

@@ -0,0 +1,52 @@
+# External mTLS with BadSSL
+
+This example calls the public BadSSL client-certificate endpoint at `https://client.badssl.com/` using a real client certificate.
+
+It is useful for checking that Multimeter sends mTLS client certificate material through the VS Code extension and CLI request transport, not just that local certificate matching logic works.
+
+## Files
+
+- `api/badssl_client.mmt` defines the public BadSSL mTLS endpoint.
+- `badssl_mtls_test.mmt` calls the API and expects HTTP 200.
+- `multimeter.mmt` configures the BadSSL client certificate with `host: "*:443"`.
+- `certs/badssl.com-client.pem` is the original PEM downloaded from BadSSL.
+- `certs/badssl-client.crt` is the certificate block split from the PEM.
+- `certs/badssl-client.key` is the encrypted private key block split from the PEM.
+- `certs/badssl-client.p12` is the same client identity as a PKCS#12 bundle.
+
+The key and PKCS#12 passphrase is the public BadSSL test passphrase: `badssl.com`. The env file includes both a PEM `cert`/`key` client and a `pfx` client; matching uses the first enabled client for `*:443`, so the PEM client is used at runtime.
+
+## Run
+
+```sh
+npx testlight run examples/professional/08_external_mtls_badssl/badssl_mtls_test.mmt
+```
+
+The runner discovers the nearest `multimeter.mmt` automatically. You can pass it explicitly if needed:
+
+```sh
+npx testlight run examples/professional/08_external_mtls_badssl/badssl_mtls_test.mmt \
+  --env-file examples/professional/08_external_mtls_badssl/multimeter.mmt
+```
+
+## External verification
+
+Use curl to confirm the same certificate works outside Multimeter:
+
+```sh
+curl -v \
+  --cert examples/professional/08_external_mtls_badssl/certs/badssl-client.crt \
+  --key examples/professional/08_external_mtls_badssl/certs/badssl-client.key \
+  --pass badssl.com \
+  https://client.badssl.com/
+
+# Equivalent PKCS#12 bundle
+curl -v \
+  --cert-type P12 \
+  --cert examples/professional/08_external_mtls_badssl/certs/badssl-client.p12:badssl.com \
+  https://client.badssl.com/
+```
+
+Without the client certificate, BadSSL returns a TLS/client-certificate failure instead of the success page.
+
+BadSSL returns an HTML page. Current runners may print a non-fatal JSON parse warning while extracting outputs from the HTML response; the mTLS smoke test still passes when the status check reports HTTP 200.

package/dist/examples/professional/08_external_mtls_badssl/api/badssl_client.mmt

@@ -0,0 +1,6 @@
+type: api
+title: BadSSL Client Certificate Endpoint
+description: Public endpoint that returns HTTP 200 only when a valid BadSSL client certificate is presented
+url: https://client.badssl.com/
+method: get
+format: text

package/dist/examples/professional/08_external_mtls_badssl/badssl_mtls_test.mmt

@@ -0,0 +1,10 @@
+type: test
+title: External BadSSL mTLS Test
+description: Calls the public BadSSL client-certificate endpoint with the included client certificate
+import:
+  badsslClient: ./api/badssl_client.mmt
+steps:
+  - call: badsslClient
+    title: Call public mTLS endpoint
+    expect:
+      status: 200

package/dist/examples/professional/08_external_mtls_badssl/multimeter.mmt

@@ -0,0 +1,13 @@
+type: env
+
+certificates:
+  clients:
+    - name: "BadSSL public client certificate"
+      host: "*:443"
+      cert: "./certs/badssl-client.crt"
+      key: "./certs/badssl-client.key"
+      passphrase_plain: "badssl.com"
+    - name: "BadSSL PKCS#12 client certificate"
+      host: "*:443"
+      pfx: "./certs/badssl-client.p12"
+      passphrase_plain: "badssl.com"

package/dist/examples/professional/09_ci_pipelines/README.md

@@ -0,0 +1,92 @@
+# CI pipelines (GitHub, GitLab, Azure)
+
+The same `.mmt` suite runs in every pipeline. Install the `mmt-testlight` npm package, run `testlight`, and publish the JUnit file.
+
+GitHub has a composite Action that does that install/run for you. GitLab and Azure use the same CLI commands.
+
+## Structure
+
+```
+09_ci_pipelines/
+├── suite.mmt              # Suite all three pipelines run
+├── smoke_get.mmt
+├── smoke_post.mmt
+├── github-actions.yml     # Copy to .github/workflows/mmt.yml
+├── gitlab-ci.yml          # Copy to .gitlab-ci.yml
+├── azure-pipelines.yml    # Copy to azure-pipelines.yml
+└── README.md
+```
+
+## Shared command
+
+```sh
+npm install -g mmt-testlight
+mkdir -p results
+testlight run suite.mmt --report junit --report-file results/junit.xml
+```
+
+From this repository:
+
+```sh
+npx mmt-testlight run examples/professional/09_ci_pipelines/suite.mmt \
+  --report junit --report-file results/junit.xml
+```
+
+`results/` is created automatically.
+
+## GitHub Actions
+
+Copy `github-actions.yml` to `.github/workflows/mmt.yml`. It uses the Multimeter Action:
+
+```yaml
+- uses: mshobeyri/testlight-action@v1
+  with:
+    file: suite.mmt
+    report: junit
+    report-file: results/junit.xml
+```
+
+If you prefer the npm CLI instead of the Action, use the same `npm install -g` / `testlight run` lines as GitLab and Azure.
+
+## GitLab CI
+
+Copy `gitlab-ci.yml` to `.gitlab-ci.yml`. GitLab publishes `results/junit.xml` as a JUnit report.
+
+## Azure Pipelines
+
+Copy `azure-pipelines.yml` to `azure-pipelines.yml`. Azure publishes the same JUnit file with `PublishTestResults@2`.
+
+## Other pipelines
+
+Any runner with Node.js can use the shared command. Jenkins example:
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Test') {
+      steps {
+        sh 'npm install -g mmt-testlight'
+        sh 'mkdir -p results'
+        sh 'testlight run suite.mmt --report junit --report-file results/junit.xml'
+      }
+    }
+  }
+  post {
+    always {
+      junit 'results/junit.xml'
+    }
+  }
+}
+```
+
+## Files
+
+| File | Description |
+|---|---|
+| `suite.mmt` | Two public smoke tests against test.mmt.dev |
+| `github-actions.yml` | GitHub Actions workflow |
+| `gitlab-ci.yml` | GitLab CI job |
+| `azure-pipelines.yml` | Azure Pipelines job |
+
+Change `suite.mmt` in each YAML if the suite is not at the repository root.

package/dist/examples/professional/09_ci_pipelines/smoke_get.mmt

@@ -0,0 +1,9 @@
+type: test
+title: CI smoke GET
+description: Public smoke check used by the GitHub, GitLab, and Azure pipeline examples
+steps:
+  - http: https://test.mmt.dev/json
+    title: Get JSON
+    method: get
+    expect:
+      status: 200

package/dist/examples/professional/09_ci_pipelines/smoke_post.mmt

@@ -0,0 +1,12 @@
+type: test
+title: CI smoke POST
+description: Public smoke check used by the GitHub, GitLab, and Azure pipeline examples
+steps:
+  - http: https://test.mmt.dev/echo
+    title: Post echo
+    method: post
+    body:
+      message: hello ci
+    expect:
+      status: 200
+      body.body.message: hello ci

package/dist/examples/professional/09_ci_pipelines/suite.mmt

@@ -0,0 +1,9 @@
+type: suite
+title: CI smoke suite
+description: Same suite the GitHub, GitLab, and Azure examples run
+tags:
+  - example
+  - ci
+items:
+  - smoke_get.mmt
+  - smoke_post.mmt

package/dist/examples/professional/10_vault_http_setenv/README.md

@@ -0,0 +1,60 @@
+# Vault over HTTP + setenv
+
+Shows how to treat **HashiCorp Vault / OpenBao** as a normal HTTP API, then promote the secret into the environment with **`setenv`** — no special Vault protocol required.
+
+The runnable path uses a **local mock** that returns a Vault KV v2 JSON shape and a bearer-protected probe. Point the same APIs at a real Vault / [test.mmt.dev](https://test.mmt.dev) when you are ready.
+
+## Flow
+
+1. Mock (or Vault) serves `GET /v1/secret/data/mmt` with `X-Vault-Token`
+2. `vault_kv_read.mmt` extracts `body.data.data.token` and can `setenv` it as `api_token`
+3. `bearer_with_env_token.mmt` calls a protected URL with `e:api_token`
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `server/vault_kv_mock.mmt` | Local Vault KV v2–shaped mock + bearer probe on port `9108` |
+| `api/vault_kv_read.mmt` | HTTP read + `outputs` / `setenv` |
+| `api/bearer_with_env_token.mmt` | Uses `e:api_token` against the protected probe |
+| `env.mmt` | Default `vault_addr` / `vault_token` / path for the mock |
+| `vault_to_api_test.mmt` | End-to-end: mock → read → setenv → bearer check |
+
+## Run (mock — no Vault install)
+
+From the repo root:
+
+```sh
+npx testlight run examples/professional/10_vault_http_setenv/vault_to_api_test.mmt \
+  --env-file examples/professional/10_vault_http_setenv/env.mmt \
+  --preset runner.mock
+```
+
+Expected: Vault mock returns `testtoken`, setenv stores it, bearer check succeeds.
+
+### In VS Code
+
+1. Open `vault_to_api_test.mmt` (or start `server/vault_kv_mock.mmt` yourself).
+2. Open `api/vault_kv_read.mmt`, load `env.mmt` / preset `runner.mock`, then **Send** — `setenv` fills `api_token` in the workspace environment.
+3. Open `api/bearer_with_env_token.mmt` and **Send**.
+
+## Use a real Vault / OpenBao
+
+Same API file; override env (token never committed):
+
+```sh
+npx testlight run examples/professional/10_vault_http_setenv/api/vault_kv_read.mmt \
+  -e vault_addr=https://vault.example.com:8200 \
+  -e vault_token="$VAULT_TOKEN" \
+  -e vault_secret_path=mmt
+```
+
+Or in VS Code: set those variables in the Environment panel, then Send `vault_kv_read.mmt`. KV v2 path and `body.data.data.*` extraction stay the same for OpenBao.
+
+Optional: after setenv, point `bearer_with_env_token.mmt` at `https://test.mmt.dev/auth/bearer` (sandbox expects `Bearer testtoken`).
+
+## Why this pattern
+
+- Vault’s API is already HTTP — Multimeter does not need `protocol: vault`
+- `setenv` is the write path into the same env bag that `e:` reads
+- Pipelines can still fetch outside Multimeter and pass `-e`; this example shows the in-product equivalent

package/dist/examples/professional/10_vault_http_setenv/api/bearer_with_env_token.mmt

@@ -0,0 +1,16 @@
+type: api
+title: Bearer auth with env token
+description: |-
+  Calls a bearer-protected endpoint using the token pulled from Vault
+  (or the mock) via `setenv` → `e:api_token`.
+
+  Default URL hits the local mock. Swap to
+  `https://test.mmt.dev/auth/bearer` to verify against the public sandbox
+  (expects `Bearer testtoken`).
+protocol: http
+method: get
+url: <<e:vault_addr>>/auth/bearer
+format: json
+auth:
+  type: bearer
+  token: e:api_token

package/dist/examples/professional/10_vault_http_setenv/api/vault_kv_read.mmt

@@ -0,0 +1,22 @@
+type: api
+title: Vault KV read
+description: |-
+  Reads a secret over plain HTTP the same way you would call Vault or OpenBao
+  KV v2 (`GET /v1/secret/data/...` + `X-Vault-Token`).
+
+  `setenv` promotes `token` into the runtime environment so later APIs can use
+  `e:api_token` / `<<e:api_token>>`.
+
+  Default URL hits the local mock in this example. Point `vault_addr` at a real
+  Vault/OpenBao and set `vault_token` to use your cluster instead.
+protocol: http
+method: get
+url: <<e:vault_addr>>/v1/secret/data/<<e:vault_secret_path>>
+headers:
+  X-Vault-Token: <<e:vault_token>>
+  Accept: application/json
+format: json
+outputs:
+  api_token: body.data.data.token
+setenv:
+  api_token: body.data.data.token

package/dist/examples/professional/10_vault_http_setenv/env.mmt

@@ -0,0 +1,21 @@
+type: env
+title: Vault HTTP example defaults
+description: |-
+  Defaults for the local Vault KV mock. Override for a real Vault/OpenBao:
+  vault_addr, vault_token, vault_secret_path.
+variables:
+  vault_addr:
+    mock: http://localhost:9108
+  vault_token:
+    mock: root
+  vault_secret_path:
+    mock: mmt
+  api_token:
+    mock: ""
+presets:
+  runner:
+    mock:
+      vault_addr: mock
+      vault_token: mock
+      vault_secret_path: mock
+      api_token: mock

package/dist/examples/professional/10_vault_http_setenv/server/vault_kv_mock.mmt

@@ -0,0 +1,45 @@
+type: server
+title: Vault KV mock
+description: |-
+  Mimics HashiCorp Vault / OpenBao KV v2 read responses so the
+  Multimeter HTTP + setenv flow can be demonstrated without a real Vault.
+  Also exposes a bearer-protected probe that accepts the secret token.
+port: 9108
+cors: true
+endpoints:
+  - method: get
+    path: /v1/secret/data/mmt
+    status: 200
+    format: json
+    # Same nested shape as Vault KV v2: data.data.<key>
+    body:
+      request_id: mock-request
+      data:
+        data:
+          token: testtoken
+          api_url: https://test.mmt.dev
+        metadata:
+          version: 1
+  - method: get
+    path: /auth/bearer
+    match:
+      headers:
+        Authorization: Bearer testtoken
+    status: 200
+    format: json
+    body:
+      authenticated: true
+      message: token accepted
+  - method: get
+    path: /auth/bearer
+    status: 401
+    format: json
+    body:
+      authenticated: false
+      message: missing or invalid bearer token
+fallback:
+  status: 404
+  format: json
+  body:
+    errors:
+      - path not found

package/dist/examples/professional/10_vault_http_setenv/vault_to_api_test.mmt

@@ -0,0 +1,22 @@
+type: test
+title: Vault HTTP setenv → protected API
+description: |-
+  Starts a Vault-shaped mock, reads a secret over HTTP, promotes the token
+  with setenv, then calls a bearer-protected API on test.mmt.dev.
+import:
+  vaultMock: ./server/vault_kv_mock.mmt
+  vaultRead: ./api/vault_kv_read.mmt
+  bearerCheck: ./api/bearer_with_env_token.mmt
+steps:
+  - run: vaultMock
+  - call: vaultRead
+    id: secret
+    expect:
+      status: 200
+      api_token: testtoken
+  - setenv:
+      api_token: ${secret.api_token}
+  - call: bearerCheck
+    expect:
+      status: 200
+    report: all

package/dist/guides/agent-workflow.md

@@ -0,0 +1,75 @@
+# Multimeter agent workflow (MCP-first)
+
+When the user asks to **create, modify, validate, format, or run** any `.mmt` file, use the **Multimeter MCP server tools first**. Do not explore npm packages, CLIs, or shell workarounds before calling MCP. Do not web-search Multimeter syntax.
+
+## Golden rule
+
+**If the task involves a `.mmt` file, start with Multimeter MCP tools in the first tool-call batch.**
+
+Do **not** first try:
+- `testlight`, `npx testlight`, or npm install/run (unless MCP is unavailable — then use `testlight scaffold` / docs)
+- `node dist/mcp/server.js` or the `mmt-mcp` binary
+- Reading Multimeter source, tarball contents, or package.json to find a runner
+- Guessing YAML syntax from memory or random repo files
+- Inventing a new test from blank without `scaffold_test`
+- Rewriting an entire `.mmt` file when the user asked to change one part
+
+## Decision tree
+
+| User intent | First MCP tool(s) | Then |
+|-------------|-------------------|------|
+| Generate test from API | **`scaffold_test`** | Write yaml → minimal edits → **`validate` → `format`** |
+| Need few-shot shape | **`list_examples`** (see `goldenSmoke`) | Mirror pair; still call `scaffold_test` |
+| Inspect one API | **`api_card`** | Prefer over full file / OpenAPI dump |
+| Tighten asserts (after run or from outputs) | **`suggest_assertions`** | Patch only → **`validate` → `format`** |
+| Create or change other types | `read_documentation(topic)` (pack **min**) | Patch → **`validate` → `format`** |
+| Change existing `.mmt` file | (docs only if needed) | **Patch only** → **`validate` → `format`** |
+| List APIs | `discover_api` | Then `api_card` / `scaffold_test` |
+| Run or execute `.mmt` | `run({ file, workspaceRoot })` | Report tool JSON; if user wants stronger asserts → `suggest_assertions` |
+| Unsure of syntax | `read_documentation` (min; `pack: full` if needed) | Local docs only — no web |
+| Offline / no MCP | see `offline-agent.md` | `testlight docs` → `scaffold` → `validate` |
+
+## Generate test from API (required)
+
+1. Optional: `list_examples` and mirror **`goldenSmoke`** (do not invent a different structure).
+2. `scaffold_test({ workspaceRoot, apiPath, strategy?: "smoke"|"example" })`
+3. Write `yaml` to `suggestedPath` (or user path).
+4. Apply **only minimal** edits (asserts, inputs, title).
+5. **`validate({ file, workspaceRoot })` until `valid: true`.**
+6. **`format({ file, workspaceRoot })` after validate passes** (required on generate).
+7. `run` only when the user asks to execute.
+8. If the user then wants stronger asserts from a response: `suggest_assertions` → patch → validate → format.
+
+## Modify workflow (required)
+
+When the user asks to **modify**, **update**, **fix**, or **add steps** to a `.mmt` `file:`
+
+1. `read_documentation(topic: "<type>")` only when syntax is unclear (pack **min**).
+2. If helpful, `api_card` / `discover_api`.
+3. **Patch only** — change the few lines needed. **Do not rewrite the whole file** unless the user explicitly asks for a rewrite/regenerate.
+4. **`validate` immediately after every edit** until `valid: true`.
+5. **`format` after validate passes.**
+6. Only call `run` when the user asks to execute.
+
+## Run → tighten asserts (optional)
+
+When the user wants better assertions after a successful (or inspected) run:
+
+1. `suggest_assertions` with `apiPath` and/or response `body` / `bodyFile`
+2. Patch `expect` / `assert` lines only
+3. `validate` → `format`
+
+## Validation + format are mandatory
+
+After **every** generate or modify on `.mmt` files:
+
+1. `validate` until valid  
+2. `format`  
+before telling the user the task is done.
+
+## YAML rules (always)
+
+- Output valid Multimeter YAML only.
+- First non-comment line must be `type: <api|test|env|...>`.
+- Never add YAML comments (`#`).
+- Use snake_case tokens: `e:api_url`, `i:user_id`, `r:uuid`, `c:epoch_ms`.

package/dist/guides/general.md

@@ -0,0 +1,64 @@
+This folder teaches an AI how to **answer questions** about Multimeter and decide **when to generate or edit** `.mmt` files.
+
+**When using VS Code Copilot with the Multimeter extension:** call Multimeter **MCP tools first** (`read_documentation`, `discover_api`, `validate`, `format`, `run`). See `AI/agent-workflow.md`.
+
+For actual YAML generation or modification, always go through `AI/generate.md`.
+
+The AI should:
+- Understand what each `type` (`api`, `test`, `env`, `doc`, `suite`) is for.
+- Decide whether the user needs **an explanation** or **new/edited YAML**.
+- Minimize tokens by reading only the specific generator file it needs.
+
+Short mental model of file types:
+- `type: api` → describe one HTTP/WebSocket endpoint.
+- `type: test` → describe flows that call APIs/tests and assert behavior.
+- `type: env` → define environment variables and presets.
+- `type: doc` → describe documentation over existing `.mmt` files.
+- `type: suite` → group and run multiple tests, APIs, or other suites.
+- `type: server` → define a mock server with endpoints, matching, and responses.
+- `type: report` → structured test results (generated by runs, viewable in the editor).
+
+When you are the AI, follow these rules:
+
+1. **Decide intent first**
+	- If the user asks "how" or "why" (no explicit request to create/edit a file):
+	  - Explain concepts in plain language.
+	  - Use small inline examples.
+	  - Do **not** open generator files unless you need exact shapes.
+	- If the user explicitly asks to create/edit a `.mmt` `file:`
+	  - Open **`AI/generate.md`**.
+	  - Follow its instructions to choose the type and generator.
+
+2. **Token conventions (snake_case)**
+	- Always show environment tokens in **snake_case**, for example:
+	  - `e:api_url`, `e:auth_token`, `e:user_id`.
+	  - Embedded: `<<e:api_url>>/users`, `Bearer <<e:auth_token>>`.
+	- Inputs: `i:user_id`, `<<i:user_id>>`.
+	- Random values: `r:uuid`, `r:first_name`, `r:last_name`, `r:epoch_ms`.
+	- Current/time values: `c:date`, `c:epoch`, `c:epoch_ms`.
+	- Use bare tokens as standalone YAML values; use `<< >>` only when embedding inside larger strings.
+
+3. **Answering common question types**
+	- "How do I call this endpoint?"
+	  - Explain briefly.
+	  - If the user wants a file, go to `generate.md` and build a `type: api` example.
+	- "How do I write a test that does X then Y?"
+	  - Explain tests and flows.
+	  - If a file is requested, go to `generate.md` and build a `type: test` example.
+	- "How do I manage/dev/prod environments?"
+	  - Explain env files and presets.
+	  - If a file is requested, go to `generate.md` and build a `type: env` example.
+	- "How do I generate API docs?"
+	  - Explain doc files.
+	  - If a file is requested, go to `generate.md` and build a `type: doc` example.
+	- "How do I run multiple tests together?"
+	  - Explain suite files.
+	  - If a file is requested, go to `generate.md` and build a `type: suite` example.
+
+4. **Safety and style**
+	- Use 2‑space indentation in all YAML examples.
+	- Prefer small, focused examples.
+	- Do not invent new fields or token formats.
+	- When unsure, propose the **minimal valid change** and explain it.
+
+Your goal here is to **decide what to do** and provide good explanations; when it is time to actually write YAML, defer to `AI/generate.md` and the more detailed `AI/generate-*.md` files.