@plune-ai/cli 0.11.1 → 0.13.0

package/README.md

@@ -100,7 +100,7 @@ provider API key is read from the environment based on `provider.type`:
 | `plune report` | Re-render the most recent run. Flags: `--format`, `-o`. |
 | `plune diff <baseline> <current>` | Compare two `plune run --format json` outputs and report pass→fail regressions. Flags: `--fail-on-regression`, `--format`, `-o`. |
 | `plune init` | Scaffold `plune.yaml`, a sample dataset, and `.env.example`. Flags: `--yes` (non-interactive), `--force`. |
-| `plune login` | Save a [Plune platform](https://plune.ai/platform) API token so `sync` and `ingest` can reach it. The token is **checked against the API before it is saved**, so a wrong one fails here rather than two commands later. Get one at `https://beta.plune.ai` → Settings → API tokens. Flags: `--token <token>` (omit to paste it or pipe it via stdin), `--skip-verify` (save without checking, for offline setup). |
+| `plune login` | Save a [Plune platform](https://plune.ai/platform) API token so `sync` and `ingest` can reach it. The token is **checked against the API before it is saved**, so a wrong one fails here rather than two commands later. Get one at `https://beta.plune.ai` → Settings → API tokens. Flags: `--token <token>` (omit to paste it or pipe it via stdin), `--skip-verify` (save without checking, for offline setup). In CI, skip this step: every platform command reads `PLUNE_TOKEN` from the environment first, and the saved login only when it is not set. |
 | `plune logout` | Remove the saved token. |
 | `plune sync` | Upload the latest local run to the platform. Flags: `--file <path>` to send a specific run JSON. |
 | `plune run import <file>` | Turn a **JUnit XML** or **Playwright JSON** report into a run in Plune. Needs no provider key — nothing is generated. Flags: `--format junit\|playwright-json` (detected from the file when omitted), `--key <externalKey>` to land several reports in one run (with `PLUNE_SHARED_RUN=1` — see below), `--create` to offer unmatched tests to the review queue. |
@@ -110,10 +110,13 @@ provider API key is read from the environment based on `provider.type`:
 | `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 six months** (ask Plune to put it back), 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. 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 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 plan grep <id>` | Print a [test plan](https://docs.plune.ai/platform/plans/) as **one `--grep` pattern** — `npx playwright test --grep "$(plune plan grep <id>)"` or `npx vitest run -t "$(plune plan grep <id>)"` runs exactly what the plan collects. Each case contributes its title path from the `path-title` key the reporter wrote (the file left out, `[ >#]+` between the segments — a space for Playwright, jest, mocha and vitest ≤ 4, ` > ` for vitest 5), escaped, joined with `\|`; a case without one goes in by title. The pattern is all that reaches stdout; the summary — how many cases, how many keyed — goes to stderr. An empty plan prints `(?!)`, which matches nothing, because an empty `--grep` would run everything. |
 
 Global flags: `-c, --config <path>` · `-v, --verbose` · `--no-color`.
 
-**Exit codes:** `0` everything passed · `1` an assertion failed · `2` configuration or execution error.
+**Exit codes:** `0` everything passed · `1` an assertion failed · `2` configuration or execution error · `3` `pull` refused to overwrite uncommitted changes · `4` `push` had refusals.
 
 ## Already running tests? Bring the results in
 
@@ -122,7 +125,7 @@ suite, there is nothing to generate — the results exist and only have to arriv
 costs nothing beyond a Plune token.
 
 ```bash
-plune login
+plune login                           # once, on your machine; in CI export PLUNE_TOKEN instead
 plune run import ./junit.xml          # Jest, Vitest, pytest, PHPUnit, Surefire, Cypress, …
 plune run import ./playwright.json    # or Playwright's own JSON report
 ```
@@ -158,6 +161,23 @@ job closes the run instead of the explicit `finish`.
 `plune run exec` sets it for you — anything reporting inside it, this command included, joins
 without closing.
 
+### When a test is deleted
+
+A test that vanishes from the code stays in Plune as an active case until something says otherwise.
+The run that covers the whole suite is what says it:
+
+```bash
+PLUNE_FULL_RUN=1 plune run import ./junit.xml      # or the same variable on the Playwright reporter's job
+```
+
+When that run finishes having reported everything it expected, every case its source used to
+report and did not this time is marked **detached** — not deleted, not retired: it keeps its history
+and its place, and the dashboard shows it with the run as the reason. The next result on it brings
+it back by itself. Set the variable only on the job that runs everything: a run of one file or a
+`--grep` also reports everything it expected, and with the flag it would detach the rest. A run that
+lost a shard (`notRun` is not empty) never detaches anything. `plune run start` has no list of
+tests to compare against, so the flag means nothing there.
+
 ### What the run is called
 
 A run nobody named is called after the directory, the minute it started and where it ran —
@@ -177,11 +197,14 @@ the [Plune platform](https://plune.ai/platform):
 plune login          # paste the API token from your platform settings page
 plune run            # exactly as before — the run is saved locally
 plune sync           # upload .plune/last-run.json, print the read-back URL
+plune pull           # the test cases as plune/cases.md — edit them anywhere
+plune push --dry-run # what a push would change, before it changes anything
 ```
 
 The token is stored at `~/.config/plune/credentials.json` (mode `0600`, honours `XDG_CONFIG_HOME`)
-and is never printed or logged. `PLUNE_API_URL` points `sync` at a different server — useful for a
-self-hosted backend.
+and is never printed or logged. `PLUNE_API_URL` points `sync`, `pull` and `push` at a different server —
+useful for a self-hosted backend. The Markdown format `pull` writes and `push` reads is documented at
+[docs.plune.ai/platform/cases/markdown](https://docs.plune.ai/platform/cases/markdown/).
 
 ## Programmatic API
 

package/dist/cli.cjs

@@ -512,7 +512,7 @@ var init_retry = __esm({
     "use strict";
     init_cjs_shims();
     init_errors2();
-    defaultSleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
+    defaultSleep = (ms) => new Promise((resolve7) => setTimeout(resolve7, ms));
   }
 });
 
@@ -2159,6 +2159,8 @@ function saveToken(token) {
   return file;
 }
 function loadToken() {
+  const fromEnv = process.env["PLUNE_TOKEN"]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
   try {
     const parsed = JSON.parse((0, import_node_fs.readFileSync)(credentialsFile(), "utf-8"));
     return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
@@ -2210,7 +2212,7 @@ function createClient(opts) {
   const wait = opts.wait ?? sleep;
   const base = opts.apiUrl.replace(/\/+$/, "");
   const scrub = (text2) => opts.token === "" ? text2 : text2.split(opts.token).join("***");
-  async function send(method, path13, body) {
+  async function send(method, path14, body) {
     let last = {
       kind: "unavailable",
       status: null,
@@ -2219,7 +2221,7 @@ function createClient(opts) {
     for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt += 1) {
       let res;
       try {
-        res = await doFetch(`${base}${path13}`, {
+        res = await doFetch(`${base}${path14}`, {
           method,
           headers: { "content-type": "application/json", authorization: `Bearer ${opts.token}` },
           // A DELETE carries none. Sending `"undefined"` as a body is what a naive
@@ -2247,8 +2249,8 @@ function createClient(opts) {
     return { ok: false, ...last };
   }
   return {
-    post: (path13, body) => send("POST", path13, body),
-    del: (path13) => send("DELETE", path13)
+    post: (path14, body) => send("POST", path14, body),
+    del: (path14) => send("DELETE", path14)
   };
 }
 var RETRY_DELAYS_MS, sleep;
@@ -2292,6 +2294,7 @@ function readEnv(env = process.env) {
   const environment = value(env, "PLUNE_ENV");
   const labels = list(env, "PLUNE_LABELS");
   const offerDiscovered = flag(env, "PLUNE_CREATE");
+  const full = flag(env, "PLUNE_FULL_RUN");
   return {
     config: {
       ...externalKey !== void 0 ? { externalKey } : {},
@@ -2304,7 +2307,8 @@ function readEnv(env = process.env) {
       ...labels !== void 0 ? { labels } : {},
       // Only when set: `false` here would outrank a config file that asked for it, and an unset
       // variable is not an instruction.
-      ...offerDiscovered ? { offerDiscovered } : {}
+      ...offerDiscovered ? { offerDiscovered } : {},
+      ...full ? { full } : {}
     },
     // Two names for two situations that end the same way. `SHARED_RUN` says other processes are
     // reporting into this run; `PROCEED` says the job will close it on its own schedule. Either
@@ -2459,7 +2463,11 @@ async function startRun(passed, declared) {
         const hit = keys.map((k) => resolved.get(k.value)).find((v) => typeof v === "string");
         if (typeof hit === "string") return [{ testCaseId: hit }];
         return keys[0] === void 0 ? [] : [{ externalKey: keys[0] }];
-      })
+      }),
+      // The claim travels with the list it is about (D20). A runner that could not enumerate
+      // its tests has no list, and a claim without one is nothing the platform can check —
+      // so it is not sent, rather than sent and silently meaningless.
+      ...cfg.full === true ? { full: true } : {}
     };
     if (expected !== void 0 && expected.length > EXPECTED_MAX) {
       log(`plune: ${expected.length} tests is more than the run configuration holds \u2014 reporting the first ${EXPECTED_MAX}.`);
@@ -2626,6 +2634,9 @@ async function startRun(passed, declared) {
           ...reason !== void 0 ? { reason } : {}
         });
         if (!out.ok) log(`plune: could not close run ${runId} (${out.detail || out.kind}).`);
+        else if (typeof out.body.detached === "number" && out.body.detached > 0) {
+          log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+        }
       }
       summarise();
     },
@@ -2754,14 +2765,14 @@ async function handleRunExec(options) {
   if (command === void 0) throw new RunCommandError("Nothing to run \u2014 pass a command after `--`.");
   const run = await handleRunStart(options);
   const spawnImpl = options.spawnImpl ?? import_node_child_process.spawn;
-  const code = await new Promise((resolve6) => {
+  const code = await new Promise((resolve7) => {
     const child = spawnImpl(command, args, {
       stdio: "inherit",
       shell: process.platform === "win32",
       env: { ...process.env, PLUNE_RUN: run.externalKey, PLUNE_PROCEED: "1" }
     });
-    child.on("close", (exitCode) => resolve6(exitCode ?? 1));
-    child.on("error", () => resolve6(1));
+    child.on("close", (exitCode) => resolve7(exitCode ?? 1));
+    child.on("error", () => resolve7(1));
   });
   await handleRunFinish(run.id, options);
   return code;
@@ -4020,7 +4031,7 @@ var init_sync = __esm({
     init_credentials();
     NotLoggedInError = class extends Error {
       constructor() {
-        super('Not logged in. Run "plune login" first to save your API token.');
+        super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
         this.name = "NotLoggedInError";
       }
     };
@@ -4297,7 +4308,7 @@ var init_ingest = __esm({
     init_cairn_artifact();
     IngestNotLoggedInError = class extends Error {
       constructor() {
-        super('Not logged in. Run "plune login" first to save your API token.');
+        super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
         this.name = "IngestNotLoggedInError";
       }
     };
@@ -4324,6 +4335,207 @@ var init_ingest = __esm({
   }
 });
 
+// src/cli/commands/cases.ts
+var cases_exports = {};
+__export(cases_exports, {
+  DEFAULT_CASES_FILE: () => DEFAULT_CASES_FILE,
+  DirtyFileError: () => DirtyFileError,
+  formatReport: () => formatReport,
+  handlePull: () => handlePull,
+  handlePush: () => handlePush,
+  reportCasesFailure: () => reportCasesFailure
+});
+function gitDirty(file) {
+  try {
+    const out = (0, import_node_child_process2.execFileSync)("git", ["status", "--porcelain", "--", file], {
+      cwd: path13.dirname(file),
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8"
+    });
+    return out.trim() !== "";
+  } catch {
+    return false;
+  }
+}
+async function safeErrorDetail3(res) {
+  try {
+    const body = await res.json();
+    return typeof body.error === "string" ? body.error : "";
+  } catch {
+    return "";
+  }
+}
+function tokenOf(deps) {
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new NotLoggedInError();
+  return token;
+}
+async function handlePull(deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const token = tokenOf(deps);
+  const file = path13.resolve(cwd, deps.file ?? DEFAULT_CASES_FILE);
+  if (fs15.existsSync(file) && !deps.force && (deps.isDirty ?? gitDirty)(file))
+    throw new DirtyFileError(path13.relative(cwd, file) || file);
+  const doFetch = deps.fetchImpl ?? fetch;
+  const endpoint = deps.suiteId !== void 0 ? `${apiUrl}/v1/suites/${encodeURIComponent(deps.suiteId)}/markdown` : `${apiUrl}/v1/test-cases/markdown`;
+  let res;
+  try {
+    res = await doFetch(endpoint, { headers: { authorization: `Bearer ${token}` } });
+  } catch {
+    throw new SyncNetworkError(apiUrl);
+  }
+  if (!res.ok) {
+    const detail = await safeErrorDetail3(res);
+    if (res.status === 401) throw new TokenRejectedError2();
+    throw new SyncHttpError(res.status, detail);
+  }
+  const text2 = await res.text();
+  fs15.mkdirSync(path13.dirname(file), { recursive: true });
+  fs15.writeFileSync(file, text2, "utf8");
+  return { file, cases: Number(res.headers.get("x-plune-cases") ?? "0") };
+}
+async function handlePush(deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const token = tokenOf(deps);
+  const file = path13.resolve(cwd, deps.file ?? DEFAULT_CASES_FILE);
+  let text2;
+  try {
+    text2 = fs15.readFileSync(file, "utf8");
+  } catch {
+    throw new SyncFileError(
+      `No document to push: ${file}. Run "plune pull" first (or pass a file).`
+    );
+  }
+  if (text2.trim() === "") throw new SyncFileError(`The document is empty: ${file}`);
+  const doFetch = deps.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await doFetch(`${apiUrl}/v1/test-cases/markdown${deps.dryRun ? "?dryRun=true" : ""}`, {
+      method: "POST",
+      headers: { "content-type": "text/markdown", authorization: `Bearer ${token}` },
+      body: text2
+    });
+  } catch {
+    throw new SyncNetworkError(apiUrl);
+  }
+  if (!res.ok) {
+    const detail = await safeErrorDetail3(res);
+    if (res.status === 401) throw new TokenRejectedError2();
+    throw new SyncHttpError(res.status, detail);
+  }
+  return await res.json();
+}
+function formatReport(report) {
+  const verb = (past, future) => report.dryRun ? future : past;
+  const lines = [
+    `${report.dryRun ? "Dry run \u2014 nothing written." : "Pushed."} ${report.created.length} ${verb("created", "to create")} \xB7 ${report.updated.length} ${verb("updated", "to update")} \xB7 ${report.unchanged.length} unchanged \xB7 ${report.refused.length} refused` + (report.suites.created.length > 0 ? ` \xB7 ${report.suites.created.length} suite(s) ${verb("created", "to create")}` : "")
+  ];
+  for (const r of report.refused)
+    lines.push(`  refused  line ${r.line}  ${r.title || "(no title)"} \u2014 ${r.error}`);
+  for (const w of report.warnings)
+    lines.push(`  warning  ${w.line !== void 0 ? `line ${w.line}  ` : ""}${w.message}`);
+  return lines.join("\n") + "\n";
+}
+function reportCasesFailure(err, write) {
+  if (err instanceof DirtyFileError) {
+    write(err.message + "\n");
+    return 3;
+  }
+  if (err instanceof NotLoggedInError || err instanceof TokenRejectedError2 || err instanceof SyncFileError) {
+    write(err.message + "\n");
+    return 2;
+  }
+  if (err instanceof SyncNetworkError || err instanceof SyncHttpError) {
+    write(err.message + "\n");
+    return 1;
+  }
+  return null;
+}
+var import_node_child_process2, fs15, path13, DEFAULT_CASES_FILE, DirtyFileError;
+var init_cases = __esm({
+  "src/cli/commands/cases.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_child_process2 = require("child_process");
+    fs15 = __toESM(require("fs"), 1);
+    path13 = __toESM(require("path"), 1);
+    init_api_url();
+    init_credentials();
+    init_sync();
+    DEFAULT_CASES_FILE = path13.join("plune", "cases.md");
+    DirtyFileError = class extends Error {
+      constructor(file) {
+        super(`${file} has uncommitted changes; commit them or pass --force to overwrite.`);
+        this.name = "DirtyFileError";
+      }
+    };
+  }
+});
+
+// src/cli/commands/plan.ts
+var plan_exports = {};
+__export(plan_exports, {
+  formatGrep: () => formatGrep,
+  grepFragment: () => grepFragment,
+  handlePlanGrep: () => handlePlanGrep
+});
+function grepFragment(c) {
+  const pathTitle = c.externalKeys.find((k) => k.kind === "path-title")?.value;
+  const segments = pathTitle?.split("#") ?? [c.title];
+  return (segments.length > 1 ? segments.slice(1) : segments).flatMap((s) => s.split(/ [>›] /)).map(escape).join(BOUNDARY);
+}
+function formatGrep(cases) {
+  if (cases.length === 0) return "(?!)";
+  return cases.map(grepFragment).join("|");
+}
+async function safeErrorDetail4(res) {
+  try {
+    const body = await res.json();
+    return typeof body.error === "string" ? body.error : "";
+  } catch {
+    return "";
+  }
+}
+async function handlePlanGrep(deps) {
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new NotLoggedInError();
+  const doFetch = deps.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await doFetch(`${apiUrl}/v1/plans/${encodeURIComponent(deps.planId)}/cases`, {
+      headers: { authorization: `Bearer ${token}` }
+    });
+  } catch {
+    throw new SyncNetworkError(apiUrl);
+  }
+  if (!res.ok) {
+    const detail = await safeErrorDetail4(res);
+    if (res.status === 401) throw new TokenRejectedError2();
+    throw new SyncHttpError(res.status, detail);
+  }
+  const { cases } = await res.json();
+  return {
+    pattern: formatGrep(cases),
+    cases: cases.length,
+    keyed: cases.filter((c) => c.externalKeys.some((k) => k.kind === "path-title")).length
+  };
+}
+var escape, BOUNDARY;
+var init_plan = __esm({
+  "src/cli/commands/plan.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_api_url();
+    init_credentials();
+    init_sync();
+    escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    BOUNDARY = "[ >#]+";
+  }
+});
+
 // src/cli.ts
 var cli_exports = {};
 __export(cli_exports, {
@@ -4481,23 +4693,30 @@ function createProgram() {
   runCommand.command("start").description("Open a platform run (or join one already carrying the key) and print its id").option("--key <externalKey>", "The key several processes share; generated when absent").option("--json", "Print one machine-readable line instead of prose", false).action(async (options, command) => {
     try {
       const { handleRunStart: handleRunStart2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
-      await handleRunStart2({ ...options.key !== void 0 ? { key: options.key } : {}, json: options.json });
-    } catch (err) {
-      await failRunCommand(err, verboseOf(command));
-    }
-  });
-  runCommand.command("finish").argument("<id>", "The run to close").description("Close a platform run \u2014 what the reporter tells you to do for a run left open").option("--terminate", "Record the run as cut short rather than finished", false).option("--reason <text>", "Why, for a terminated run").action(async (id, options, command) => {
-    try {
-      const { handleRunFinish: handleRunFinish2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
-      await handleRunFinish2(id, {
-        terminate: options.terminate,
-        ...options.reason !== void 0 ? { reason: options.reason } : {}
+      await handleRunStart2({
+        ...options.key !== void 0 ? { key: options.key } : {},
+        json: options.json
       });
     } catch (err) {
       await failRunCommand(err, verboseOf(command));
     }
   });
-  runCommand.command("exec").argument("<command...>", "The command to run inside the run, after `--`").description("Open a run, run a command inside it, close the run \u2014 whatever the command returns").option("--key <externalKey>", "The key several processes share; generated when absent").action(async (argv, options, command) => {
+  runCommand.command("finish").argument("<id>", "The run to close").description("Close a platform run \u2014 what the reporter tells you to do for a run left open").option("--terminate", "Record the run as cut short rather than finished", false).option("--reason <text>", "Why, for a terminated run").action(
+    async (id, options, command) => {
+      try {
+        const { handleRunFinish: handleRunFinish2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
+        await handleRunFinish2(id, {
+          terminate: options.terminate,
+          ...options.reason !== void 0 ? { reason: options.reason } : {}
+        });
+      } catch (err) {
+        await failRunCommand(err, verboseOf(command));
+      }
+    }
+  );
+  runCommand.command("exec").argument("<command...>", "The command to run inside the run, after `--`").description(
+    "Open a run, run a command inside it, close the run \u2014 whatever the command returns"
+  ).option("--key <externalKey>", "The key several processes share; generated when absent").action(async (argv, options, command) => {
     try {
       const { handleRunExec: handleRunExec2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
       process.exitCode = await handleRunExec2({
@@ -4508,7 +4727,10 @@ function createProgram() {
       await failRunCommand(err, verboseOf(command));
     }
   });
-  runCommand.command("delete").argument("<id>", "The run id \u2014 the one `plune run import` printed, or the one in the dashboard URL").description("Delete a run and everything it produced \u2014 recoverable for six months").action(async (id, _options, command) => {
+  runCommand.command("delete").argument(
+    "<id>",
+    "The run id \u2014 the one `plune run import` printed, or the one in the dashboard URL"
+  ).description("Delete a run and everything it produced \u2014 recoverable for six months").action(async (id, _options, command) => {
     try {
       const { handleRunDelete: handleRunDelete2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
       await handleRunDelete2(id);
@@ -4526,14 +4748,19 @@ function createProgram() {
   });
   runCommand.command("import").argument("<file>", "A JUnit XML or Playwright JSON report").description("Turn a report another runner wrote into a run in Plune \u2014 no provider key needed").option("--format <fmt>", "junit | playwright-json; detected from the file when omitted").option("--key <externalKey>", "The key several jobs share so their reports land in one run").option("--create", "Offer tests nothing matched to the review queue", false).action(
     async (file, options, command) => {
-      const [{ handleRunImport: handleRunImport2 }, { IMPORT_FORMATS: IMPORT_FORMATS2, UnknownFormatError: UnknownFormatError2, XmlParseError: XmlParseError2, JsonReportError: JsonReportError2 }] = await Promise.all([
+      const [
+        { handleRunImport: handleRunImport2 },
+        { IMPORT_FORMATS: IMPORT_FORMATS2, UnknownFormatError: UnknownFormatError2, XmlParseError: XmlParseError2, JsonReportError: JsonReportError2 }
+      ] = await Promise.all([
         Promise.resolve().then(() => (init_run_import(), run_import_exports)),
         Promise.resolve().then(() => (init_importers(), importers_exports))
       ]);
       const format = options.format;
       if (format !== void 0 && !IMPORT_FORMATS2.includes(format)) {
-        process.stderr.write(`Unknown --format "${format}". Use ${IMPORT_FORMATS2.join(" or ")}.
-`);
+        process.stderr.write(
+          `Unknown --format "${format}". Use ${IMPORT_FORMATS2.join(" or ")}.
+`
+        );
         process.exit(2);
         return;
       }
@@ -4626,10 +4853,10 @@ function createProgram() {
     const { handleLogin: handleLogin2, reportLoginFailure: reportLoginFailure2 } = await Promise.resolve().then(() => (init_login(), login_exports));
     try {
       const token = options.token ?? await readTokenFromStdin();
-      const { path: path13, verified } = await handleLogin2({ token, skipVerify: options.skipVerify });
+      const { path: path14, verified } = await handleLogin2({ token, skipVerify: options.skipVerify });
       process.stdout.write(
-        verified ? `Logged in. Token checked against the API and saved to ${path13}
-` : `Token saved to ${path13} WITHOUT being checked (--skip-verify).
+        verified ? `Logged in. Token checked against the API and saved to ${path14}
+` : `Token saved to ${path14} WITHOUT being checked (--skip-verify).
 `
       );
     } catch (err) {
@@ -4646,9 +4873,9 @@ function createProgram() {
     const verbose = command.optsWithGlobals().verbose === true;
     const { handleLogout: handleLogout2 } = await Promise.resolve().then(() => (init_logout(), logout_exports));
     try {
-      const { removed, path: path13 } = handleLogout2();
+      const { removed, path: path14 } = handleLogout2();
       process.stdout.write(
-        removed ? `Logged out. Removed ${path13}
+        removed ? `Logged out. Removed ${path14}
 ` : "Not logged in \u2014 nothing to remove.\n"
       );
     } catch (err) {
@@ -4695,6 +4922,77 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
+  program.command("pull").argument("[file]", "Where to write the document (default: plune/cases.md)").description(
+    "Write the project's test cases as one Markdown document (GET /v1/test-cases/markdown)"
+  ).option("--suite <id>", "Only this suite or folder and what is under it").option("--force", "Overwrite the file even when git says it has uncommitted changes", false).action(
+    async (file, options, command) => {
+      const verbose = command.optsWithGlobals().verbose === true;
+      const { handlePull: handlePull2, reportCasesFailure: reportCasesFailure2 } = await Promise.resolve().then(() => (init_cases(), cases_exports));
+      try {
+        const result = await handlePull2({
+          ...file !== void 0 ? { file } : {},
+          ...options.suite !== void 0 ? { suiteId: options.suite } : {},
+          force: options.force
+        });
+        process.stdout.write(`Pulled ${result.cases} case(s) \u2192 ${result.file}
+`);
+      } catch (err) {
+        const code = reportCasesFailure2(err, (s) => process.stderr.write(s));
+        if (code !== null) {
+          maybeStack(err, verbose);
+          process.exitCode = code;
+          return;
+        }
+        failUnexpected(err, verbose);
+      }
+    }
+  );
+  program.command("push").argument("[file]", "The document to send (default: plune/cases.md)").description(
+    "Send a Markdown document of test cases back to Plune (POST /v1/test-cases/markdown)"
+  ).option("--dry-run", "Show what would change and write nothing", false).action(async (file, options, command) => {
+    const verbose = command.optsWithGlobals().verbose === true;
+    const { handlePush: handlePush2, formatReport: formatReport2, reportCasesFailure: reportCasesFailure2 } = await Promise.resolve().then(() => (init_cases(), cases_exports));
+    try {
+      const report = await handlePush2({
+        ...file !== void 0 ? { file } : {},
+        dryRun: options.dryRun
+      });
+      process.stdout.write(formatReport2(report));
+      if (report.refused.length > 0) process.exitCode = 4;
+    } catch (err) {
+      const code = reportCasesFailure2(err, (s) => process.stderr.write(s));
+      if (code !== null) {
+        maybeStack(err, verbose);
+        process.exitCode = code;
+        return;
+      }
+      failUnexpected(err, verbose);
+    }
+  });
+  const planCommand = program.command("plan").description("Test plans on the platform \u2014 what a plan collects, as something a runner can take");
+  planCommand.command("grep").argument("<id>", "The plan").description(
+    "Print the plan's cases as one --grep pattern for the runner (GET /v1/plans/:id/cases)"
+  ).action(async (id, _options, command) => {
+    const verbose = command.optsWithGlobals().verbose === true;
+    const { handlePlanGrep: handlePlanGrep2 } = await Promise.resolve().then(() => (init_plan(), plan_exports));
+    const { reportCasesFailure: reportCasesFailure2 } = await Promise.resolve().then(() => (init_cases(), cases_exports));
+    try {
+      const out = await handlePlanGrep2({ planId: id });
+      process.stdout.write(out.pattern + "\n");
+      process.stderr.write(
+        out.cases === 0 ? "plune: the plan matches no case \u2014 the pattern matches nothing.\n" : `plune: ${out.cases} case(s) in the plan, ${out.keyed} with a test key; the rest by title.
+`
+      );
+    } catch (err) {
+      const code = reportCasesFailure2(err, (s) => process.stderr.write(s));
+      if (code !== null) {
+        maybeStack(err, verbose);
+        process.exitCode = code;
+        return;
+      }
+      failUnexpected(err, verbose);
+    }
+  });
   program.on("command:*", (operands) => {
     process.stderr.write(`Unknown command: ${operands.join(" ")}
 `);

package/dist/index.cjs

@@ -1595,6 +1595,8 @@ function credentialsFile() {
   return (0, import_node_path.join)(base, "plune", "credentials.json");
 }
 function loadToken() {
+  const fromEnv = process.env["PLUNE_TOKEN"]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
   try {
     const parsed = JSON.parse((0, import_node_fs.readFileSync)(credentialsFile(), "utf-8"));
     return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
@@ -1606,7 +1608,7 @@ function loadToken() {
 // src/cli/commands/sync.ts
 var NotLoggedInError = class extends Error {
   constructor() {
-    super('Not logged in. Run "plune login" first to save your API token.');
+    super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
     this.name = "NotLoggedInError";
   }
 };
@@ -1862,7 +1864,7 @@ async function readCairnRun(dir, deps = {}) {
 // src/cli/commands/ingest.ts
 var IngestNotLoggedInError = class extends Error {
   constructor() {
-    super('Not logged in. Run "plune login" first to save your API token.');
+    super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
     this.name = "IngestNotLoggedInError";
   }
 };

package/dist/index.js

@@ -1542,6 +1542,8 @@ function credentialsFile() {
   return join3(base, "plune", "credentials.json");
 }
 function loadToken() {
+  const fromEnv = process.env["PLUNE_TOKEN"]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
   try {
     const parsed = JSON.parse(readFileSync3(credentialsFile(), "utf-8"));
     return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
@@ -1553,7 +1555,7 @@ function loadToken() {
 // src/cli/commands/sync.ts
 var NotLoggedInError = class extends Error {
   constructor() {
-    super('Not logged in. Run "plune login" first to save your API token.');
+    super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
     this.name = "NotLoggedInError";
   }
 };
@@ -1809,7 +1811,7 @@ async function readCairnRun(dir, deps = {}) {
 // src/cli/commands/ingest.ts
 var IngestNotLoggedInError = class extends Error {
   constructor() {
-    super('Not logged in. Run "plune login" first to save your API token.');
+    super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
     this.name = "IngestNotLoggedInError";
   }
 };

package/dist/reporter-core.cjs

@@ -60,6 +60,8 @@ function credentialsFile() {
   return (0, import_node_path.join)(base, "plune", "credentials.json");
 }
 function loadToken() {
+  const fromEnv = process.env["PLUNE_TOKEN"]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
   try {
     const parsed = JSON.parse((0, import_node_fs.readFileSync)(credentialsFile(), "utf-8"));
     return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
@@ -172,6 +174,7 @@ function readEnv(env = process.env) {
   const environment = value(env, "PLUNE_ENV");
   const labels = list(env, "PLUNE_LABELS");
   const offerDiscovered = flag(env, "PLUNE_CREATE");
+  const full = flag(env, "PLUNE_FULL_RUN");
   return {
     config: {
       ...externalKey !== void 0 ? { externalKey } : {},
@@ -184,7 +187,8 @@ function readEnv(env = process.env) {
       ...labels !== void 0 ? { labels } : {},
       // Only when set: `false` here would outrank a config file that asked for it, and an unset
       // variable is not an instruction.
-      ...offerDiscovered ? { offerDiscovered } : {}
+      ...offerDiscovered ? { offerDiscovered } : {},
+      ...full ? { full } : {}
     },
     // Two names for two situations that end the same way. `SHARED_RUN` says other processes are
     // reporting into this run; `PROCEED` says the job will close it on its own schedule. Either
@@ -330,7 +334,11 @@ async function startRun(passed, declared) {
         const hit = keys.map((k) => resolved.get(k.value)).find((v) => typeof v === "string");
         if (typeof hit === "string") return [{ testCaseId: hit }];
         return keys[0] === void 0 ? [] : [{ externalKey: keys[0] }];
-      })
+      }),
+      // The claim travels with the list it is about (D20). A runner that could not enumerate
+      // its tests has no list, and a claim without one is nothing the platform can check —
+      // so it is not sent, rather than sent and silently meaningless.
+      ...cfg.full === true ? { full: true } : {}
     };
     if (expected !== void 0 && expected.length > EXPECTED_MAX) {
       log(`plune: ${expected.length} tests is more than the run configuration holds \u2014 reporting the first ${EXPECTED_MAX}.`);
@@ -497,6 +505,9 @@ async function startRun(passed, declared) {
           ...reason !== void 0 ? { reason } : {}
         });
         if (!out.ok) log(`plune: could not close run ${runId} (${out.detail || out.kind}).`);
+        else if (typeof out.body.detached === "number" && out.body.detached > 0) {
+          log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+        }
       }
       summarise();
     },

package/dist/reporter-core.d.cts

@@ -188,6 +188,16 @@ interface ReporterConfig {
      * how somebody says "yes, tell me what we are running that you do not know about".
      */
     offerDiscovered?: boolean;
+    /**
+     * This run is the whole suite (`PLUNE_FULL_RUN=1`, D20).
+     *
+     * Sent as `configuration.full` beside `expected`. When such a run finishes having reported
+     * everything it expected, the platform moves the cases this source used to report and did not
+     * this time to `detached` — a test that vanished from the code stops looking alive. Off by
+     * default because nothing here can tell a suite that shrank from `-g smoke` or a single file:
+     * only whoever typed the command knows, so the CI job that runs everything is the one to set it.
+     */
+    full?: boolean;
     /** Transport seam — the same one `sync.ts` uses so tests need no server. */
     fetchImpl?: typeof fetch;
     /** Where a line for the operator goes. Defaults to stderr. */

package/dist/reporter-core.d.ts

@@ -188,6 +188,16 @@ interface ReporterConfig {
      * how somebody says "yes, tell me what we are running that you do not know about".
      */
     offerDiscovered?: boolean;
+    /**
+     * This run is the whole suite (`PLUNE_FULL_RUN=1`, D20).
+     *
+     * Sent as `configuration.full` beside `expected`. When such a run finishes having reported
+     * everything it expected, the platform moves the cases this source used to report and did not
+     * this time to `detached` — a test that vanished from the code stops looking alive. Off by
+     * default because nothing here can tell a suite that shrank from `-g smoke` or a single file:
+     * only whoever typed the command knows, so the CI job that runs everything is the one to set it.
+     */
+    full?: boolean;
     /** Transport seam — the same one `sync.ts` uses so tests need no server. */
     fetchImpl?: typeof fetch;
     /** Where a line for the operator goes. Defaults to stderr. */

package/dist/reporter-core.js

@@ -17,6 +17,8 @@ function credentialsFile() {
   return join(base, "plune", "credentials.json");
 }
 function loadToken() {
+  const fromEnv = process.env["PLUNE_TOKEN"]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
   try {
     const parsed = JSON.parse(readFileSync(credentialsFile(), "utf-8"));
     return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
@@ -129,6 +131,7 @@ function readEnv(env = process.env) {
   const environment = value(env, "PLUNE_ENV");
   const labels = list(env, "PLUNE_LABELS");
   const offerDiscovered = flag(env, "PLUNE_CREATE");
+  const full = flag(env, "PLUNE_FULL_RUN");
   return {
     config: {
       ...externalKey !== void 0 ? { externalKey } : {},
@@ -141,7 +144,8 @@ function readEnv(env = process.env) {
       ...labels !== void 0 ? { labels } : {},
       // Only when set: `false` here would outrank a config file that asked for it, and an unset
       // variable is not an instruction.
-      ...offerDiscovered ? { offerDiscovered } : {}
+      ...offerDiscovered ? { offerDiscovered } : {},
+      ...full ? { full } : {}
     },
     // Two names for two situations that end the same way. `SHARED_RUN` says other processes are
     // reporting into this run; `PROCEED` says the job will close it on its own schedule. Either
@@ -287,7 +291,11 @@ async function startRun(passed, declared) {
         const hit = keys.map((k) => resolved.get(k.value)).find((v) => typeof v === "string");
         if (typeof hit === "string") return [{ testCaseId: hit }];
         return keys[0] === void 0 ? [] : [{ externalKey: keys[0] }];
-      })
+      }),
+      // The claim travels with the list it is about (D20). A runner that could not enumerate
+      // its tests has no list, and a claim without one is nothing the platform can check —
+      // so it is not sent, rather than sent and silently meaningless.
+      ...cfg.full === true ? { full: true } : {}
     };
     if (expected !== void 0 && expected.length > EXPECTED_MAX) {
       log(`plune: ${expected.length} tests is more than the run configuration holds \u2014 reporting the first ${EXPECTED_MAX}.`);
@@ -454,6 +462,9 @@ async function startRun(passed, declared) {
           ...reason !== void 0 ? { reason } : {}
         });
         if (!out.ok) log(`plune: could not close run ${runId} (${out.detail || out.kind}).`);
+        else if (typeof out.body.detached === "number" && out.body.detached > 0) {
+          log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+        }
       }
       summarise();
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plune-ai/cli",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "AI-powered assertion testing for LLM apps — write assertions, run them against any provider, get a pass/fail report (local, CI, or diff).",
   "keywords": [
     "ai",