@plune-ai/cli 0.30.2 → 0.31.0

package/README.md

@@ -128,7 +128,7 @@ the last resort, used only when `PLUNE_TOKEN` is set nowhere else. Nothing write
 | `plune run exec -- <command>` | Open a run, run the command inside it, close the run — and exit with whatever the command returned. Sets `PLUNE_SHARED_RUN` for you, so anything reporting inside joins that run. Flags: `--key <externalKey>`, `--name <text>` (as on `run start`), `--fail-on-failures` to exit with [the gate](#a-release-gate---fail-on-failures)'s code instead — or with the command's own when no result reached the run. |
 | `plune run delete <id>` | Delete a run and everything it produced — its results and the review-queue entries it raised. Approved test cases and the audit log stay. **Recoverable for 30 days** (an owner of the project can put it back from Settings → Bin), then gone for good. No prompt: it is your data, and this command belongs in scripts. |
 | `plune run report` | Replay `.plune/pending-results.jsonl` — send what the reporter could not. The lines of one reporter run go back as one run, with the commit and branch the reporter recorded. Once every result has gone the file is renamed to `pending-results.<time>.sent.jsonl`; if anything did not go, it stays as it was. Flags: `--file <path>`. |
-| `plune ingest [dir]` | Record a [Cairn](https://github.com/plune-ai/cairn) run in Plune. Omit `[dir]` for the newest run under `./runs`, or name the directory holding `report.json`. Generated cases arrive as **review proposals** — nothing is created until a person approves it. |
+| `plune ingest [dir]` | Record a [Cairn](https://github.com/plune-ai/cairn) run in Plune. Omit `[dir]` for the newest run under `./runs`, or name the directory holding `report.json`. Generated cases arrive as **review proposals** — nothing is created until a person approves it. Against a platform with `POST /v1/jobs` the ingest is also reported as a job (kind `ingest`, counting the cases sent, linked to the run it landed in) that ends completed, or failed with the error text if the ingest fails; as with `sync`, an older platform is not told and a job report never fails the ingest or changes its exit code. |
 | `plune pull [file]` | Write the project's test cases as **one Markdown document** — Testomat's classical format, plus Plune's own columns — to `plune/cases.md` (or `[file]`). Refuses to overwrite a file git sees as modified; `--force` overrides, `--suite <id>` takes one suite or folder and what is under it. |
 | `plune push [file] [--dry-run]` | Send the document back. Cases are matched by `id`; a block without one becomes a draft; an unknown id is refused by line; **nothing is deleted**. Prints the report — created, updated, unchanged, refused, warnings — and with `--dry-run` writes nothing. Exit `4` when anything was refused. |
 | `plune requirements import <file.md>` | Import requirements from a **Markdown file** (an SRS, a PRD, a page exported from a wiki). With no mapping flags it lists the tables and sections the file has and exits `0`; with `--table` or `--sections` it is a **dry run** that writes nothing until you add `--yes`. See [Requirements from a Markdown file](#requirements-from-a-markdown-file). Needs a Plune platform that serves `POST /v1/projects/:id/requirements/import` (plune-ai/plune#1621). |
@@ -424,6 +424,37 @@ The shard that is the Nth also prints `plune: run closed` just above that line,
   and leaves the run open, as `PLUNE_SHARED_RUN` does: close it with `plune run finish`.
 - With `--fail-on-failures`, the shard that closes the run gates on its summary; the others have no verdict yet.
 
+#### A combination per job of a matrix: `PLUNE_CONFIGURATION`
+
+The jobs of a matrix of browsers and systems report into one run, each under its own combination of
+configuration values (plune-ai/plune#1251):
+
+```yaml
+strategy:
+  matrix:
+    browser: [Chrome, Firefox]
+    os: [Windows, macOS]
+env:
+  PLUNE_RUN: ${{ github.run_id }}-${{ github.run_attempt }}
+  PLUNE_SHARED_RUN: 1
+  PLUNE_CONFIGURATION: "Browser=${{ matrix.browser }};Operating system=${{ matrix.os }}"
+```
+
+`PLUNE_CONFIGURATION` is `Group=Value` pairs split by `;`, with the names of the groups and values as in
+Settings → Configurations. Case does not matter, spaces around a name or a value are dropped, and so is an
+empty pair (`;;`, a `;` at the end); a value may hold `=`, since a pair splits at its first one. Every results
+batch of `plune run import` and of the Playwright reporter carries it, and Plune files the results under that
+combination of the run: one the run already has (a run launched from the dashboard with configurations, joined
+by its key), or one it adds. A value that is not in Settings is taken as sent, marked "not in the list". Unset
+or blank, the batch is sent as before. The run is closed once at the end, as above.
+
+- A pair without `=`, without a group or without a value, or one group named twice, is a configuration error:
+  nothing is sent and the command fails.
+- Every job of a run names the same groups. Plune refuses with 422 a batch that names other groups, or one that
+  would take the run past its limits (25 combinations, 40 000 results to expect); its message is printed as it
+  came, and the batch goes to the fallback file like any other refused batch.
+- The fallback file keeps the combination, and `plune run report` sends the batch back into it.
+
 ### A time limit for the import
 
 The whole `plune run import` stops after 600 seconds by default, so a platform that stops answering cannot hold a CI job until its own timeout kills it. Raise it for a very large report, or turn it off with `0`: