@plune-ai/cli 0.28.0 → 0.29.0

package/README.md

@@ -132,7 +132,9 @@ the last resort, used only when `PLUNE_TOKEN` is set nowhere else. Nothing write
 | `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). |
+| `plune requirements links <file.md>` | Import a **traceability matrix** (a Markdown table of requirement key to test) as links between requirements and cases. With no flags it lists the tables the file has and exits `0`; with `--table`, `--requirement-column` and `--test-column` it is a **dry run** that writes nothing until you add `--yes`. See [Links from a traceability matrix](#links-from-a-traceability-matrix). Needs a platform that serves `POST /v1/projects/:id/requirements/import/links` (plune-ai/plune#1608). |
 | `plune verify` | Compare the project's **automated cases** with the Playwright tests in the code, **read-only** (plune-ai/plune#1291). Prints both sides: cases in Plune that the code no longer has (already `detached`, or one a full run would detach) and tests in the code that Plune has no case for. A test is matched by the id it names (`PluneId` annotation or `@P<id>` in its title), else by its `path-title` key. Nothing is written to Plune and no id is added to your source. Playwright only. Flags: `--from <file>` (a saved `playwright test --list --reporter=json`, instead of running Playwright), `--playwright-config <path>`, `--json`, `--fail-on-drift` (exit `1` when either side has something the other lacks). |
+| `plune ids [--write]` | Write the Plune **case id of each Playwright test that names none** into a mapfile, `plune/ids.json` (`{ "<path-title>": "<case id>" }`), instead of editing your test files (plune-ai/plune#1291). A **dry run** unless `--write`: it prints what it would add. Only tests whose case Plune already holds get an entry (matched by the `path-title` key); a test with no case yet is listed and skipped. Idempotent: entries are only added, never overwritten or removed (an entry for a test no longer in the code is kept and listed), the file is sorted so diffs stay small, and nothing is written when nothing changes. A mapfile that is not a JSON object of strings is refused (exit `2`) and left as it is. Playwright only. The Playwright reporter reads the mapfile: an entry names the case after the `PluneId` annotation, `@P<id>` and a metadata attachment, and before the `playwright-id` and `path-title` keys, so a renamed test keeps its case when the entry is updated with `plune ids --write` (override the path with `PLUNE_IDS_FILE` or the reporter option `idsFile`). Flags: `--write`, `--file <path>` (default `plune/ids.json`), `--from <file>`, `--playwright-config <path>`, `--json`. Exit codes as `plune verify`. |
 | `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. |
 | `plune run grep <run> [--failed]` | Print a run's **automated** cases as one `--grep` pattern, built the way `plan grep` builds a plan's — so the commands Plune shows for a run work as they are: `npx playwright test --grep "$(plune run grep <run-id> --failed)"` re-runs an automated run's failures where your tests run (Plune starts no CI), and `PLUNE_RUN=<key> npx playwright test --grep "$(plune run grep <key>)"` runs the automated half of a mixed run launched without a plan. `<run>` is the run's id (a UUID) or its key (`rk_` and ten hex); anything else is refused with exit `2` before anything is sent, and a key no run carries exits `1`. The cases are the ones the run expected — cases added on its page among them, run or not — or holds a result of; manual cases are left out. `--failed` keeps the cases whose latest result the platform counts as failed or broken, so a muted case's failure stays out, as from **Re-run N failed**. Only the pattern reaches stdout; how many cases were taken and how many left out goes to stderr; nothing taken prints `(?!)`. Needs a Plune that serves `GET /v1/runs/:id/cases` (plune-ai/plune#1333). |
 
@@ -196,6 +198,20 @@ Inside a `--table` the names are `key`, `title` or `text` (one of the two), `des
 
 `--json` prints the platform's answer instead. The project is the only one of the account, or `--project <id>` / `PLUNE_PROJECT` (a token only works in the project it was minted in). Exit `0` on success, `2` for a flag combination that cannot work (`--table` with `--sections`, `--title-column` with `--text-column`, a `--table "<n>:..."` spec with the single-table column flags), an unreadable or over-limit file, or a rejected token, `1` when the platform refuses (400, 403, 409 a key taken meanwhile, 413) or does not have the routes yet.
 
+### Links from a traceability matrix
+
+Requirements documents often end with a table of requirement id to test. `plune requirements links <file.md>` imports it as links between requirements and cases, in the same two steps as `requirements import`: it sends the file as it is, and you say which table and which two columns.
+
+```bash
+plune requirements links matrix.md                     # lists the tables, exit 0
+plune requirements links matrix.md --table 0 --requirement-column "Requirement" --test-column "Test"   # dry run
+plune requirements links matrix.md --table 0 --requirement-column "Requirement" --test-column "Test" --yes
+```
+
+A requirement is matched by its key (import the requirements first, with `--key-column`). A test is matched by the exact title of a case, or for an automated case by its source path (`e2e/login.spec.ts` or `e2e/login.spec.ts#title`); put several tests in one cell on separate lines (`<br>`). A requirement cell with several keys is split by `--separator` (1 to 3 characters, default `,`; nothing else is guessed). The report lists what it would link, what is already linked, and every row that matched nothing, with the reason (unknown key, archived requirement, no such case, a title that names several cases). A second import changes nothing. Links never change a requirement's coverage, which still comes from each case's last result.
+
+Exit `0` after a dry run or a write, even when rows are unmatched; `--fail-on-unmatched` makes any unmatched row exit `1`. A wrong flag or file is `2`; a read-only member, a rejected mapping or a matrix over 2000 rows (after splitting) is `1` with the platform's reason. `--json` prints the platform's answer; `--project <id>` / `PLUNE_PROJECT` picks the project.
+
 ### A release gate: `--fail-on-failures`
 
 `plune run finish`, `plune run exec`, `plune run import` and `plune sync` take `--fail-on-failures`. The exit

package/dist/cli.cjs

@@ -555,22 +555,22 @@ var init_prices = __esm({
 });
 
 // src/providers/cost.ts
-function priceFrom(price, usage2) {
-  return usage2.input_tokens / 1e3 * price.input_per_1k_usd + usage2.output_tokens / 1e3 * price.output_per_1k_usd;
+function priceFrom(price, usage3) {
+  return usage3.input_tokens / 1e3 * price.input_per_1k_usd + usage3.output_tokens / 1e3 * price.output_per_1k_usd;
 }
-function resolveCost(usage2, model, reportedCostUsd, overrides, deps = {}) {
+function resolveCost(usage3, model, reportedCostUsd, overrides, deps = {}) {
   const table = deps.table ?? PRICE_TABLE;
   const warn = deps.warn ?? defaultWarn;
   const override = overrides?.[model];
   if (override !== void 0) {
-    return priceFrom(override, usage2);
+    return priceFrom(override, usage3);
   }
   if (reportedCostUsd !== void 0) {
     return reportedCostUsd;
   }
   const tablePrice = table[model];
   if (tablePrice !== void 0) {
-    return priceFrom(tablePrice, usage2);
+    return priceFrom(tablePrice, usage3);
   }
   warn(
     `plune: no price for model "${model}" \u2014 reporting cost_usd=0. Set pricing["${model}"] in plune.yaml to track its cost.`
@@ -629,8 +629,8 @@ function makeAnthropicProvider(config, env, pricing) {
         throw normalizeProviderError(err, apiKey, ENV_VAR);
       }
     },
-    estimateCost(usage2, reportedCostUsd) {
-      return { cost_usd: resolveCost(usage2, config.model, reportedCostUsd, pricing) };
+    estimateCost(usage3, reportedCostUsd) {
+      return { cost_usd: resolveCost(usage3, config.model, reportedCostUsd, pricing) };
     }
   };
 }
@@ -696,8 +696,8 @@ function makeOpenAiCompatibleProvider(opts) {
         throw normalizeProviderError(err, apiKey, apiKeyEnv);
       }
     },
-    estimateCost(usage2, reportedCostUsd) {
-      return { cost_usd: resolveCost(usage2, config.model, reportedCostUsd, pricing) };
+    estimateCost(usage3, reportedCostUsd) {
+      return { cost_usd: resolveCost(usage3, config.model, reportedCostUsd, pricing) };
     }
   };
 }
@@ -800,8 +800,8 @@ function makeEstimateProvider(config, pricing) {
     complete: () => Promise.reject(
       new Error("The --dry-run provider only estimates cost; it never calls a model.")
     ),
-    estimateCost: (usage2, reportedCostUsd) => ({
-      cost_usd: resolveCost(usage2, config.model, reportedCostUsd, pricing)
+    estimateCost: (usage3, reportedCostUsd) => ({
+      cost_usd: resolveCost(usage3, config.model, reportedCostUsd, pricing)
     })
   };
 }
@@ -1781,8 +1781,8 @@ async function runRow(p) {
   const maxTokens = p.providerConfig.max_tokens ?? DEFAULT_MAX_TOKENS2;
   if (p.dryRun) {
     const est = estimateUsage(prompt5, maxTokens);
-    const usage3 = { ...est, cost_usd: p.provider.estimateCost(est).cost_usd };
-    return { vars: p.row.vars, output: null, cached: false, usage: usage3, assertions: [] };
+    const usage4 = { ...est, cost_usd: p.provider.estimateCost(est).cost_usd };
+    return { vars: p.row.vars, output: null, cached: false, usage: usage4, assertions: [] };
   }
   const key = cacheKey(
     {
@@ -1795,7 +1795,7 @@ async function runRow(p) {
     p.policyVersion
   );
   let output;
-  let usage2;
+  let usage3;
   let cached = false;
   let cacheSaved;
   let hit = p.noCache ? void 0 : p.cache.get(key, p.cacheMaxAgeMs !== void 0 ? { maxAgeMs: p.cacheMaxAgeMs } : {});
@@ -1816,7 +1816,7 @@ async function runRow(p) {
   if (hit !== void 0) {
     output = hit.output;
     cached = true;
-    usage2 = {
+    usage3 = {
       input_tokens: hit.usage.input_tokens,
       output_tokens: hit.usage.output_tokens,
       cost_usd: 0
@@ -1836,7 +1836,7 @@ async function runRow(p) {
         prompt_resolved: prompt5
       });
       output = res.output;
-      usage2 = {
+      usage3 = {
         input_tokens: res.usage.input_tokens,
         output_tokens: res.usage.output_tokens,
         // Prefer the provider-reported actual cost (res.cost_usd) when present; resolveCost still
@@ -1884,7 +1884,7 @@ async function runRow(p) {
       break;
     }
   }
-  const finalUsage = { ...usage2, cost_usd: usage2.cost_usd + judgeCost };
+  const finalUsage = { ...usage3, cost_usd: usage3.cost_usd + judgeCost };
   return {
     vars: p.row.vars,
     output,
@@ -2853,7 +2853,14 @@ function repoRootOf(dir, stopAt) {
     if (here === stopAt || (0, import_node_path2.dirname)(here) === here) return void 0;
   }
 }
-function errorContextOf(attempt, home = (0, import_node_os2.homedir)()) {
+function errorContextFields(attempt, home = (0, import_node_os2.homedir)()) {
+  const { text: text2, omitted: omitted2 } = cutErrorContext(attempt, home);
+  return {
+    ...text2 !== "" ? { errorContext: text2 } : {},
+    ...omitted2 > 0 ? { errorContextOmitted: omitted2 } : {}
+  };
+}
+function cutErrorContext(attempt, home) {
   const text2 = attempt.errors.map((e) => e.text).filter((t) => t !== "").join("\n\n");
   return cut(machineless(text2, attempt.repoRoot, home));
 }
@@ -2879,7 +2886,7 @@ function pathIn(path17) {
   return new RegExp(`${url}${escaped}`, /^[A-Za-z]:$/.test(parts[0]) ? "gi" : "g");
 }
 function cut(text2) {
-  if (jsonBytes(text2) <= TEXT_LIMIT) return text2;
+  if (jsonBytes(text2) <= TEXT_LIMIT) return { text: text2, omitted: 0 };
   const lines = text2.split("\n");
   const size = lines.map((line) => jsonBytes(line) + 2);
   const budget = TEXT_LIMIT - jsonBytes(omitted(lines.length));
@@ -2888,7 +2895,8 @@ function cut(text2) {
   let tail = lines.length;
   while (head < tail && used + size[head] <= budget / 2) used += size[head++];
   while (tail > head && used + size[tail - 1] <= budget) used += size[--tail];
-  return [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n");
+  const kept = [...lines.slice(0, head), ...lines.slice(tail)].join("\n");
+  return { text: [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n"), omitted: text2.length - kept.length };
 }
 function chosen({ status, errors }) {
   if (status === "timedOut") {
@@ -5008,7 +5016,7 @@ function pendingOf(r, retry, ctx) {
     })),
     testFile: ""
   };
-  const errorContext = errorContextOf(attempt);
+  const errorContext = errorContextFields(attempt);
   const failure = FAILED.has(status) ? failureOf(attempt) : void 0;
   const pkg2 = labelOf(r, "package");
   const where = (key.includes("#") ? key.split("#")[0] : pkg2)?.replace(/^[A-Za-z][A-Za-z0-9_-]+:(?![\\/])/, "");
@@ -5032,7 +5040,7 @@ function pendingOf(r, retry, ctx) {
         retry
       }
     } : {},
-    ...errorContext !== "" ? { errorContext } : {},
+    ...errorContext,
     ...failure !== void 0 ? { failure } : {},
     ...files.length > 0 ? { files } : {}
   };
@@ -5362,7 +5370,7 @@ function pendingFrom(spec, test, result, file, titles, ctx) {
   const stated = statedIdOf(test, spec.title ?? "");
   const expected = test.expectedStatus;
   const attempt = attemptOf(result, file, ctx);
-  const errorContext = errorContextOf(attempt);
+  const errorContext = errorContextFields(attempt);
   const failure = NOT_FAILED.has(attempt.status) ? void 0 : failureOf(attempt);
   const files = filesOf(attempt);
   const keys = [
@@ -5392,7 +5400,7 @@ function pendingFrom(spec, test, result, file, titles, ctx) {
         ...result.workerIndex !== void 0 ? { worker: String(result.workerIndex) } : {}
       }
     } : {},
-    ...errorContext !== "" ? { errorContext } : {},
+    ...errorContext,
     ...failure !== void 0 ? { failure } : {},
     ...files.length > 0 ? { files } : {}
   };
@@ -6509,12 +6517,18 @@ __export(requirements_import_exports, {
   MAX_MARKDOWN_BYTES: () => MAX_MARKDOWN_BYTES,
   RequirementsImportError: () => RequirementsImportError,
   buildImportBody: () => buildImportBody,
+  cut: () => cut2,
+  flat: () => flat,
   formatDiscover: () => formatDiscover,
   formatReport: () => formatReport2,
   handleRequirementsImport: () => handleRequirementsImport,
   parseMap: () => parseMap,
   parseTableSpec: () => parseTableSpec,
-  reportRequirementsImportFailure: () => reportRequirementsImportFailure
+  plural: () => plural,
+  readMarkdown: () => readMarkdown,
+  refusal: () => refusal,
+  reportRequirementsImportFailure: () => reportRequirementsImportFailure,
+  resolveProject: () => resolveProject
 });
 function parseMap(flag2, raw) {
   const out = {};
@@ -6801,12 +6815,94 @@ var init_requirements_import = __esm({
   }
 });
 
+// src/cli/commands/requirements-links.ts
+var requirements_links_exports = {};
+__export(requirements_links_exports, {
+  buildLinksBody: () => buildLinksBody,
+  formatLinks: () => formatLinks,
+  formatLinksDiscover: () => formatLinksDiscover,
+  handleRequirementsLinks: () => handleRequirementsLinks
+});
+function buildLinksBody(f) {
+  if (f.table === void 0 && f.requirementColumn === void 0 && f.testColumn === void 0 && f.separator === void 0) return null;
+  if (f.table === void 0) return usage2("--requirement-column, --test-column and --separator need --table <n>. Run without flags to see which tables the file has.");
+  if (!/^\d+$/.test(f.table)) usage2(`--table is the number of the table in the list (0, 1, ...), not "${f.table}".`);
+  if (f.requirementColumn === void 0 || f.requirementColumn.trim() === "") usage2("--table needs --requirement-column <header> (the column with the requirement keys).");
+  if (f.testColumn === void 0 || f.testColumn.trim() === "") usage2("--table needs --test-column <header> (the column with the test titles or paths).");
+  const body = { table: Number(f.table), requirementColumn: f.requirementColumn, testColumn: f.testColumn };
+  if (f.separator !== void 0) {
+    if (f.separator.length < 1 || f.separator.length > 3) usage2(`--separator is 1 to 3 characters, not "${f.separator}".`);
+    body["requirementSeparator"] = f.separator;
+  }
+  return body;
+}
+async function handleRequirementsLinks(deps) {
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const mapping = buildLinksBody(deps);
+  const markdown = readMarkdown(deps.cwd ?? process.cwd(), deps.file);
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new RequirementsImportError('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.', 2);
+  const client = createClient({ apiUrl, token, ...deps.fetchImpl !== void 0 ? { fetchImpl: deps.fetchImpl } : {} });
+  const projectId = await resolveProject(client, deps.project, apiUrl);
+  const base = `/v1/projects/${encodeURIComponent(projectId)}/requirements/import`;
+  if (mapping === null) {
+    const out2 = await client.post(`${base}/discover`, { markdown });
+    if (!out2.ok) throw refusal(out2, apiUrl, projectId);
+    return { step: "discover", result: out2.body };
+  }
+  const out = await client.post(`${base}/links`, { markdown, dryRun: deps.yes !== true, ...mapping });
+  if (!out.ok) throw refusal(out, apiUrl, projectId);
+  return { step: "links", report: out.body };
+}
+function formatLinksDiscover(file, r) {
+  const out = [`${file}: ${plural(r.tables.length, "table")}`, ""];
+  if (r.tables.length === 0) out.push("  (none)");
+  for (const t of r.tables) {
+    const mark = t.unreadable !== void 0 ? `   cannot be read: ${t.unreadable}` : "";
+    out.push(`  #${t.index}  line ${t.line}  ${t.heading === null ? "(no heading)" : `"${flat(t.heading)}"`}  ${cut2(t.headers.map(flat).join(" | "), 100)}  ${plural(t.rowCount, "row")}${mark}`);
+  }
+  if (r.truncated) out.push("", "The file has more tables than are listed here.");
+  out.push("", "Pick the matrix and name its two columns (a dry run, nothing is written):", `  plune requirements links ${file} --table <n> --requirement-column <header> --test-column <header>`);
+  return out.join("\n") + "\n";
+}
+function formatLinks(report) {
+  const s = report.summary;
+  const out = [`link ${s.link} \xB7 unchanged ${s.unchanged} \xB7 unmatched ${s.unmatched}`];
+  for (const action of ["unmatched", "link", "unchanged"]) {
+    const rows = report.items.filter((i) => i.action === action);
+    if (rows.length === 0) continue;
+    out.push("", `${action} (${rows.length})`);
+    for (const i of rows.slice(0, SHOWN2)) {
+      out.push(`  line ${i.line}  ${i.key === "" ? "-" : i.key}  ->  ${i.test === "" ? "-" : cut2(flat(i.test), 80)}  - ${flat(i.reason)}`);
+    }
+    if (rows.length > SHOWN2) out.push(`  ... and ${rows.length - SHOWN2} more (--json lists every row)`);
+  }
+  out.push("", report.applied ? `applied \u2014 ${plural(s.link, "link")} created.` : "dry run \u2014 nothing was written; add --yes to apply");
+  return out.join("\n") + "\n";
+}
+var usage2, SHOWN2;
+var init_requirements_links = __esm({
+  "src/cli/commands/requirements-links.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_client();
+    init_api_url();
+    init_credentials();
+    init_requirements_import();
+    usage2 = (message) => {
+      throw new RequirementsImportError(message, 2);
+    };
+    SHOWN2 = 50;
+  }
+});
+
 // src/cli/commands/verify.ts
 var verify_exports = {};
 __export(verify_exports, {
   compare: () => compare,
   formatVerify: () => formatVerify,
   handleVerify: () => handleVerify,
+  loadSources: () => loadSources,
   testsOfListing: () => testsOfListing
 });
 function testsOfListing(listing) {
@@ -6859,7 +6955,7 @@ function runPlaywrightList(args, cwd) {
     throw new SyncFileError(`could not list the Playwright tests${stderr ? `: ${stderr}` : ""}`);
   }
 }
-async function handleVerify(deps) {
+async function loadSources(deps) {
   const get = platformGet(deps);
   let raw;
   if (deps.from !== void 0) {
@@ -6891,7 +6987,11 @@ async function handleVerify(deps) {
     cases.push(...page.testCases);
     cursor = page.nextCursor;
   } while (cursor !== null);
-  return compare(testsOfListing(listing), cases);
+  return { code: testsOfListing(listing), cases };
+}
+async function handleVerify(deps) {
+  const { code, cases } = await loadSources(deps);
+  return compare(code, cases);
 }
 function formatVerify(r) {
   const lines = [];
@@ -6925,6 +7025,111 @@ var init_verify = __esm({
   }
 });
 
+// src/cli/commands/ids.ts
+var ids_exports = {};
+__export(ids_exports, {
+  DEFAULT_IDS_FILE: () => DEFAULT_IDS_FILE,
+  formatIds: () => formatIds,
+  handleIds: () => handleIds,
+  planIds: () => planIds,
+  readMap: () => readMap,
+  serializeMap: () => serializeMap
+});
+function readMap(file) {
+  if (!(0, import_node_fs9.existsSync)(file)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs9.readFileSync)(file, "utf8"));
+  } catch {
+    throw new SyncFileError(`${file} is not valid JSON; fix or remove it, nothing was written`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || Object.values(parsed).some((v) => typeof v !== "string" || v === ""))
+    throw new SyncFileError(
+      `${file} must be an object of path-title to case id strings; nothing was written`
+    );
+  return parsed;
+}
+function planIds(code, cases, current) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const c of cases)
+    if (c.type === "automated" && c.state !== "deprecated") {
+      for (const k of c.externalKeys ?? []) if (k.kind === "path-title") byPath.set(k.value, c);
+    }
+  const added = {};
+  const noCase = [];
+  let covered = 0;
+  for (const t of code) {
+    if (t.id !== void 0 || current[t.pathTitle] !== void 0) covered++;
+    else {
+      const hit = byPath.get(t.pathTitle);
+      if (hit === void 0) noCase.push(t.pathTitle);
+      else added[t.pathTitle] = hit.id;
+    }
+  }
+  const inCode = new Set(code.map((t) => t.pathTitle));
+  return {
+    added,
+    covered,
+    noCase: noCase.sort(compareKeys),
+    orphaned: Object.keys(current).filter((k) => !inCode.has(k)).sort(compareKeys)
+  };
+}
+function serializeMap(map) {
+  const sorted = {};
+  for (const k of Object.keys(map).sort(compareKeys)) sorted[k] = map[k];
+  return JSON.stringify(sorted, null, 2) + "\n";
+}
+async function handleIds(deps) {
+  const file = deps.file ?? DEFAULT_IDS_FILE;
+  const current = readMap(file);
+  const { code, cases } = await loadSources(deps);
+  const plan = planIds(code, cases, current);
+  let written = false;
+  if (deps.write === true && Object.keys(plan.added).length > 0) {
+    try {
+      (0, import_node_fs9.mkdirSync)((0, import_node_path5.dirname)(file), { recursive: true });
+      (0, import_node_fs9.writeFileSync)(file, serializeMap({ ...current, ...plan.added }));
+    } catch {
+      throw new SyncFileError(`cannot write ${file}`);
+    }
+    written = true;
+  }
+  return { file, ...plan, written };
+}
+function formatIds(r, write) {
+  const n = Object.keys(r.added).length;
+  const lines = [];
+  if (n > 0) {
+    lines.push(`${write ? "Added to" : "Would add to"} ${r.file} (${n}):`);
+    for (const k of Object.keys(r.added).sort(compareKeys)) lines.push(`  ${k}  ->  ${r.added[k]}`);
+  }
+  if (r.noCase.length > 0) {
+    lines.push(`In the code, no case in Plune yet, nothing to write (${r.noCase.length}):`);
+    for (const k of r.noCase) lines.push(`  ${k}`);
+  }
+  if (r.orphaned.length > 0) {
+    lines.push(`In ${r.file}, test no longer in the code, kept (${r.orphaned.length}):`);
+    for (const k of r.orphaned) lines.push(`  ${k}`);
+  }
+  lines.push(
+    n === 0 ? `Nothing to write: ${r.covered} test(s) already have an id.` : write ? `${r.covered} already had an id. ${r.file} written.` : `${r.covered} already had an id. Dry run: nothing was written; add --write.`
+  );
+  return lines.join("\n") + "\n";
+}
+var import_node_fs9, import_node_path5, DEFAULT_IDS_FILE, compareKeys;
+var init_ids = __esm({
+  "src/cli/commands/ids.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_fs9 = require("fs");
+    import_node_path5 = require("path");
+    init_verify();
+    init_sync();
+    DEFAULT_IDS_FILE = "plune/ids.json";
+    compareKeys = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  }
+});
+
 // src/cli.ts
 var cli_exports = {};
 __export(cli_exports, {
@@ -6934,8 +7139,8 @@ module.exports = __toCommonJS(cli_exports);
 init_cjs_shims();
 init_api_url();
 var import_commander = require("commander");
-var import_node_fs9 = require("fs");
-var import_node_path5 = require("path");
+var import_node_fs10 = require("fs");
+var import_node_path6 = require("path");
 var import_node_url = require("url");
 
 // src/util/duration.ts
@@ -6951,8 +7156,8 @@ function parseDuration(text2) {
 }
 
 // src/cli.ts
-var __dirname = (0, import_node_path5.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
-var pkg = JSON.parse((0, import_node_fs9.readFileSync)((0, import_node_path5.join)(__dirname, "..", "package.json"), "utf-8"));
+var __dirname = (0, import_node_path6.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+var pkg = JSON.parse((0, import_node_fs10.readFileSync)((0, import_node_path6.join)(__dirname, "..", "package.json"), "utf-8"));
 function toFormat(s) {
   return s === "json" || s === "markdown" ? s : "console";
 }
@@ -6961,7 +7166,7 @@ function shouldColor(outputPath) {
 }
 function writeReport(text2, outputPath) {
   if (outputPath !== void 0) {
-    (0, import_node_fs9.writeFileSync)(outputPath, text2);
+    (0, import_node_fs10.writeFileSync)(outputPath, text2);
   } else {
     process.stdout.write(text2 + "\n");
   }
@@ -7006,7 +7211,7 @@ function createProgram() {
   program.hook("preAction", async (_program, action) => {
     const { loadEnv: loadEnv2 } = await Promise.resolve().then(() => (init_env(), env_exports));
     const { config } = action.optsWithGlobals();
-    if (config !== void 0) loadEnv2((0, import_node_path5.dirname)((0, import_node_path5.resolve)(config)));
+    if (config !== void 0) loadEnv2((0, import_node_path6.dirname)((0, import_node_path6.resolve)(config)));
     loadEnv2(process.cwd());
   });
   const runCommand = program.command("run").description("Run assertions against a dataset").option("--dry-run", "Estimate cost/tokens; do not call the model", false).option("--config <path>", "Path to plune.yaml config file").option(
@@ -7286,7 +7491,7 @@ ${missed.map((m) => `  - ${m}`).join("\n")}
       Promise.resolve().then(() => (init_report(), report_exports)),
       Promise.resolve().then(() => (init_reporters(), reporters_exports))
     ]);
-    const cwd = globals.config !== void 0 ? (0, import_node_path5.dirname)((0, import_node_path5.resolve)(globals.config)) : process.cwd();
+    const cwd = globals.config !== void 0 ? (0, import_node_path6.dirname)((0, import_node_path6.resolve)(globals.config)) : process.cwd();
     try {
       const result = handleReport2({ cwd });
       const text2 = renderReport2(result, toFormat(options.format), {
@@ -7383,7 +7588,7 @@ ${missed.map((m) => `  - ${m}`).join("\n")}
     const globals = command.optsWithGlobals();
     const verbose = globals.verbose === true;
     const { handleSync: handleSync2, reportSyncFailure: reportSyncFailure2 } = await Promise.resolve().then(() => (init_sync(), sync_exports));
-    const cwd = globals.config !== void 0 ? (0, import_node_path5.dirname)((0, import_node_path5.resolve)(globals.config)) : process.cwd();
+    const cwd = globals.config !== void 0 ? (0, import_node_path6.dirname)((0, import_node_path6.resolve)(globals.config)) : process.cwd();
     try {
       const { id, url, gate } = await handleSync2({
         cwd,
@@ -7472,7 +7677,7 @@ ${missed.map((m) => `  - ${m}`).join("\n")}
       failUnexpected(err, verbose);
     }
   });
-  const requirementsCommand = program.command("requirements").description("Requirements on the platform \u2014 import them from a Markdown file");
+  const requirementsCommand = program.command("requirements").description("Requirements on the platform \u2014 import them, or their links to tests, from a Markdown file");
   requirementsCommand.command("import").argument("<file>", "A Markdown file (UTF-8, at most 1 MiB)").description(
     "Import requirements from a Markdown file. With no mapping flags it lists the tables and sections found; with them it is a dry run until --yes"
   ).option(
@@ -7499,6 +7704,30 @@ ${missed.map((m) => `  - ${m}`).join("\n")}
       failUnexpected(err, verbose);
     }
   });
+  requirementsCommand.command("links").argument("<file>", "A Markdown file with a traceability matrix (UTF-8, at most 1 MiB)").description(
+    "Import a traceability matrix (requirement key -> test) as links. With no flags it lists the tables found; with them it is a dry run until --yes"
+  ).option("--table <n>", "The table with the matrix (its number from the list)").option("--requirement-column <header>", "The column holding the requirement keys").option("--test-column <header>", "The column holding the tests: an exact case title or a source path, one per line").option("--separator <text>", 'Splits a requirement cell into several keys, 1 to 3 characters (default ",")').option("--project <id>", "The project (default: PLUNE_PROJECT, else the only project of the account)").option("--yes", "Write it. Without it the import is a dry run", false).option("--json", "Print the platform\u2019s answer as JSON", false).option("--fail-on-unmatched", "Exit 1 when any requirement or test of the matrix matched nothing", false).action(async (file, options, command) => {
+    const verbose = command.optsWithGlobals().verbose === true;
+    const { handleRequirementsLinks: handleRequirementsLinks2, formatLinksDiscover: formatLinksDiscover2, formatLinks: formatLinks2 } = await Promise.resolve().then(() => (init_requirements_links(), requirements_links_exports));
+    const { reportRequirementsImportFailure: reportRequirementsImportFailure2 } = await Promise.resolve().then(() => (init_requirements_import(), requirements_import_exports));
+    try {
+      const res = await handleRequirementsLinks2({ file, ...options });
+      if (options.json === true) {
+        process.stdout.write(JSON.stringify(res.step === "discover" ? res.result : res.report, null, 2) + "\n");
+      } else {
+        process.stdout.write(res.step === "discover" ? formatLinksDiscover2(file, res.result) : formatLinks2(res.report));
+      }
+      if (options.failOnUnmatched === true && res.step === "links" && res.report.summary.unmatched > 0) process.exitCode = 1;
+    } catch (err) {
+      const code = reportRequirementsImportFailure2(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)"
@@ -7548,6 +7777,32 @@ ${missed.map((m) => `  - ${m}`).join("\n")}
       }
     }
   );
+  program.command("ids").description(
+    "Write the Plune case id of each Playwright test that names none into plune/ids.json (dry run unless --write); test sources are not touched"
+  ).option("--write", "Write the file; without it only shows what would be written", false).option("--file <path>", "The mapfile", "plune/ids.json").option("--from <file>", "A saved `playwright test --list --reporter=json` document instead of running Playwright").option("--playwright-config <path>", "Passed to `playwright test --config`").option("--json", "Print the report as JSON", false).action(
+    async (options, command) => {
+      const verbose = verboseOf(command);
+      const { handleIds: handleIds2, formatIds: formatIds2 } = await Promise.resolve().then(() => (init_ids(), ids_exports));
+      const { reportCasesFailure: reportCasesFailure2 } = await Promise.resolve().then(() => (init_cases(), cases_exports));
+      try {
+        const report = await handleIds2({
+          write: options.write,
+          file: options.file,
+          ...options.from === void 0 ? {} : { from: options.from },
+          ...options.playwrightConfig === void 0 ? {} : { playwrightConfig: options.playwrightConfig }
+        });
+        process.stdout.write(options.json ? JSON.stringify(report, null, 2) + "\n" : formatIds2(report, options.write));
+      } 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(" ")}
 `);
@@ -7559,7 +7814,7 @@ function isMainModule() {
   const entry = process.argv[1];
   if (entry === void 0) return false;
   try {
-    return (0, import_node_fs9.realpathSync)(entry) === (0, import_node_fs9.realpathSync)((0, import_node_url.fileURLToPath)(importMetaUrl));
+    return (0, import_node_fs10.realpathSync)(entry) === (0, import_node_fs10.realpathSync)((0, import_node_url.fileURLToPath)(importMetaUrl));
   } catch {
     return false;
   }

package/dist/reporter-core.cjs

@@ -36,6 +36,7 @@ __export(reporter_core_exports, {
   appendBatch: () => appendBatch,
   ciCommit: () => ciCommit,
   createClient: () => createClient,
+  errorContextFields: () => errorContextFields,
   errorContextOf: () => errorContextOf,
   failureOf: () => failureOf,
   filesOf: () => filesOf,
@@ -449,6 +450,16 @@ function repoRootOf(dir, stopAt) {
   }
 }
 function errorContextOf(attempt, home = (0, import_node_os2.homedir)()) {
+  return cutErrorContext(attempt, home).text;
+}
+function errorContextFields(attempt, home = (0, import_node_os2.homedir)()) {
+  const { text, omitted: omitted2 } = cutErrorContext(attempt, home);
+  return {
+    ...text !== "" ? { errorContext: text } : {},
+    ...omitted2 > 0 ? { errorContextOmitted: omitted2 } : {}
+  };
+}
+function cutErrorContext(attempt, home) {
   const text = attempt.errors.map((e) => e.text).filter((t) => t !== "").join("\n\n");
   return cut(machineless(text, attempt.repoRoot, home));
 }
@@ -484,7 +495,7 @@ function pathIn(path3) {
 }
 var fileNameOf = (name) => /^(?:file:\/\/|[\\/]|~[\\/]|[A-Za-z]:[\\/])/.test(name) ? name.split(/[\\/]/).pop() ?? "" : name;
 function cut(text) {
-  if (jsonBytes(text) <= TEXT_LIMIT) return text;
+  if (jsonBytes(text) <= TEXT_LIMIT) return { text, omitted: 0 };
   const lines = text.split("\n");
   const size = lines.map((line) => jsonBytes(line) + 2);
   const budget = TEXT_LIMIT - jsonBytes(omitted(lines.length));
@@ -493,7 +504,8 @@ function cut(text) {
   let tail = lines.length;
   while (head < tail && used + size[head] <= budget / 2) used += size[head++];
   while (tail > head && used + size[tail - 1] <= budget) used += size[--tail];
-  return [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n");
+  const kept = [...lines.slice(0, head), ...lines.slice(tail)].join("\n");
+  return { text: [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n"), omitted: text.length - kept.length };
 }
 var omitted = (lines) => `\u2026[omitted ${lines} lines]\u2026`;
 var METADATA_TYPE = "application/plune.metadata+json";
@@ -1585,6 +1597,7 @@ function resultKey(testId, retry) {
   appendBatch,
   ciCommit,
   createClient,
+  errorContextFields,
   errorContextOf,
   failureOf,
   filesOf,

package/dist/reporter-core.d.cts

@@ -541,6 +541,16 @@ declare function repoRootOf(dir: string, stopAt?: string): string | undefined;
  * searched for credentials: the platform does that before its own cut (ADR-0005).
  */
 declare function errorContextOf(attempt: FailedAttempt, home?: string): string;
+/**
+ * The `errorContext` and `errorContextOmitted` keys of a result (plune-ai/plune#1281 AC-03), ready to spread:
+ * none for an empty text, and `errorContextOmitted` only when the cut took something out, a whole number of at
+ * least 1 (the platform refuses 0). Counted in characters of the text as it would have been sent (`.length`,
+ * the unit the platform counts in), never bytes; the `…[omitted N lines]…` marker is not counted.
+ */
+declare function errorContextFields(attempt: FailedAttempt, home?: string): {
+    errorContext?: string;
+    errorContextOmitted?: number;
+};
 /**
  * The files the runner kept for one attempt, whatever its status: a screenshot of a test that passed
  * is how a person sees what it checked (plune-ai/plune#913). Which of them the platform takes, the
@@ -642,4 +652,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type FrozenSummary, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };
+export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type FrozenSummary, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextFields, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };

package/dist/reporter-core.d.ts

@@ -541,6 +541,16 @@ declare function repoRootOf(dir: string, stopAt?: string): string | undefined;
  * searched for credentials: the platform does that before its own cut (ADR-0005).
  */
 declare function errorContextOf(attempt: FailedAttempt, home?: string): string;
+/**
+ * The `errorContext` and `errorContextOmitted` keys of a result (plune-ai/plune#1281 AC-03), ready to spread:
+ * none for an empty text, and `errorContextOmitted` only when the cut took something out, a whole number of at
+ * least 1 (the platform refuses 0). Counted in characters of the text as it would have been sent (`.length`,
+ * the unit the platform counts in), never bytes; the `…[omitted N lines]…` marker is not counted.
+ */
+declare function errorContextFields(attempt: FailedAttempt, home?: string): {
+    errorContext?: string;
+    errorContextOmitted?: number;
+};
 /**
  * The files the runner kept for one attempt, whatever its status: a screenshot of a test that passed
  * is how a person sees what it checked (plune-ai/plune#913). Which of them the platform takes, the
@@ -642,4 +652,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type FrozenSummary, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };
+export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type FrozenSummary, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextFields, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };

package/dist/reporter-core.js

@@ -400,6 +400,16 @@ function repoRootOf(dir, stopAt) {
   }
 }
 function errorContextOf(attempt, home = homedir2()) {
+  return cutErrorContext(attempt, home).text;
+}
+function errorContextFields(attempt, home = homedir2()) {
+  const { text, omitted: omitted2 } = cutErrorContext(attempt, home);
+  return {
+    ...text !== "" ? { errorContext: text } : {},
+    ...omitted2 > 0 ? { errorContextOmitted: omitted2 } : {}
+  };
+}
+function cutErrorContext(attempt, home) {
   const text = attempt.errors.map((e) => e.text).filter((t) => t !== "").join("\n\n");
   return cut(machineless(text, attempt.repoRoot, home));
 }
@@ -435,7 +445,7 @@ function pathIn(path3) {
 }
 var fileNameOf = (name) => /^(?:file:\/\/|[\\/]|~[\\/]|[A-Za-z]:[\\/])/.test(name) ? name.split(/[\\/]/).pop() ?? "" : name;
 function cut(text) {
-  if (jsonBytes(text) <= TEXT_LIMIT) return text;
+  if (jsonBytes(text) <= TEXT_LIMIT) return { text, omitted: 0 };
   const lines = text.split("\n");
   const size = lines.map((line) => jsonBytes(line) + 2);
   const budget = TEXT_LIMIT - jsonBytes(omitted(lines.length));
@@ -444,7 +454,8 @@ function cut(text) {
   let tail = lines.length;
   while (head < tail && used + size[head] <= budget / 2) used += size[head++];
   while (tail > head && used + size[tail - 1] <= budget) used += size[--tail];
-  return [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n");
+  const kept = [...lines.slice(0, head), ...lines.slice(tail)].join("\n");
+  return { text: [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n"), omitted: text.length - kept.length };
 }
 var omitted = (lines) => `\u2026[omitted ${lines} lines]\u2026`;
 var METADATA_TYPE = "application/plune.metadata+json";
@@ -1535,6 +1546,7 @@ export {
   appendBatch,
   ciCommit,
   createClient,
+  errorContextFields,
   errorContextOf,
   failureOf,
   filesOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plune-ai/cli",
-  "version": "0.28.0",
+  "version": "0.29.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",