@allurereport/plugin-agent 3.5.0 → 3.6.0

package/README.md

@@ -16,7 +16,7 @@ This plugin writes AI-friendly markdown summaries for a test run. It is designed
 flows like:
 
 ```shell
-ALLURE_AGENT_OUTPUT=./out/agent-report npx allure run -- npm test
+npx allure agent -- npm test
 ```
 
 When enabled, the plugin writes:
@@ -38,8 +38,8 @@ accept. See [the enrichment loop guide](../../docs/agent_enrichment_loop.md).
 
 ## Verification Standard
 
-- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure run`. It preserves the original console logs and adds agent-mode artifacts when you need them.
-- Use `allure run` for smoke checks too, even when the change is small or mechanical.
+- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.
+- Use `allure agent` for smoke checks too, even when the change is small or mechanical.
 - Only skip agent mode when it is impossible or when you are debugging agent mode itself.
 
 ## Skills-First Workflow
@@ -84,7 +84,24 @@ export default defineConfig({
 });
 ```
 
-You can also enable it through an environment variable:
+The preferred CLI entrypoint is:
+
+```shell
+npx allure agent -- npm test
+```
+
+You can provide an explicit expectations file and output directory when you need deterministic paths:
+
+```shell
+npx allure agent \
+  --output ./out/agent-report \
+  --expectations ./out/agent-expected.yaml \
+  -- npm test
+```
+
+That command uses an agent-only profile by default, so configured presentation and export plugins such as Awesome, Dashboard, or TestOps are ignored for that run.
+
+You can also enable the plugin through lower-level environment variables when you need direct env control:
 
 ```shell
 ALLURE_AGENT_OUTPUT=./out/agent-report npx allure run -- npm test
@@ -184,7 +201,7 @@ markdown and `manifest/findings.jsonl`.
 
 The intended usage pattern is:
 
-1. Run tests with `allure run -- <command>`.
+1. Run tests with `allure agent -- <command>`.
 2. Watch `manifest/run.json` and `manifest/test-events.jsonl` while the run is active.
 3. Review `index.md` plus the manifest files.
 4. If evidence is weak, add steps, attachments, labels, or parameters.
@@ -252,9 +269,17 @@ the same policy in a project-level skill or agent prompt, you can start with:
 ```md
 ## Allure Agent Mode Instructions
 
-- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure run`. It preserves the original console logs and adds agent-mode artifacts when you need them.
-- Use `allure run` for smoke checks too, even when the change is small or mechanical.
+- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.
+- Use `allure agent` for smoke checks too, even when the change is small or mechanical.
 - Only skip agent mode when it is impossible or when you are debugging agent mode itself.
+- After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly.
+- Use `allure agent latest` to reopen the newest run when `--output` was omitted.
+- Use `allure agent state-dir` to inspect where the current project stores its latest-agent state.
+- Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning.
+- Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests.
+- Use `--rerun-preset review|failed|unsuccessful|all`, repeated `--rerun-environment <id>`, and repeated `--rerun-label name=value` when you need a narrower rerun selection from the previous output.
+- Use `ALLURE_AGENT_STATE_DIR` when you need to override where the current project stores latest-agent state for `latest`, `state-dir`, or `--rerun-latest`.
+- Use `ALLURE_AGENT_*` with `allure run` only as the lower-level fallback when you need direct environment control.
 - Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted rerun.
 - Run tests with `ALLURE_AGENT_OUTPUT` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.
 - Enrich only the intended tests. Add real steps for real setup, actions, and assertions.

package/dist/guidance.d.ts

@@ -5,14 +5,14 @@ export type EnrichmentActionDefinition = {
     guidance: string;
 };
 export declare const ENRICHMENT_ACTIONS_BY_CHECK_NAME: Record<string, EnrichmentActionDefinition>;
-export declare const AGENT_ENRICHMENT_WORKFLOW: readonly ["Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted enrichment iteration.", "Run tests with `allure run -- <command>` and `ALLURE_AGENT_OUTPUT` enabled.", "Inspect `manifest/run.json`, tail `manifest/test-events.jsonl`, then review `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` before editing tests.", "Enrich only the intended tests, rerun the same scope, and compare the rerun against `manifest/expected.json` when present.", "Accept the rerun only when scope is clean, evidence is strong enough to review, and no high-confidence dummy findings remain."];
-export declare const AGENT_VERIFICATION_RULES: readonly ["If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure run`. It preserves the original console logs and adds agent-mode artifacts when you need them.", "Use `allure run` for smoke checks too, even when the change is small or mechanical.", "Only skip agent mode when it is impossible or when you are debugging agent mode itself."];
-export declare const AGENT_SMALL_TEST_CHANGE_WORKFLOW: readonly ["Create a fresh temp `ALLURE_AGENT_OUTPUT` and `ALLURE_AGENT_EXPECTATIONS` for the touched scope before closing the task.", "Run the touched scope with `allure run`, even if the goal is only a smoke check after a mechanical change such as typing cleanup, mock refactors, or helper extraction.", "Review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` before making any final claim."];
+export declare const AGENT_ENRICHMENT_WORKFLOW: readonly ["Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted enrichment iteration.", "Run tests with `allure agent --output <dir> --expectations <file> -- <command>`.", "After each test run, print the `index.md` path from that output directory so collaborators can open the run overview quickly.", "Use `allure agent latest` to recover the newest output directory when a prior run omitted `--output`.", "Use `allure agent state-dir` to inspect where the current project stores its latest-agent state.", "Use `ALLURE_AGENT_STATE_DIR` when you need to override where the current project stores latest-agent state for `latest`, `state-dir`, or `--rerun-latest`.", "Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning.", "Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests through Allure testplan support. Add `--rerun-preset`, repeated `--rerun-environment`, or repeated `--rerun-label name=value` filters when you need a narrower rerun slice.", "Inspect `manifest/run.json`, tail `manifest/test-events.jsonl`, then review `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` before editing tests.", "Enrich only the intended tests, rerun the same scope, and compare the rerun against `manifest/expected.json` when present.", "Accept the rerun only when scope is clean, evidence is strong enough to review, and no high-confidence dummy findings remain."];
+export declare const AGENT_VERIFICATION_RULES: readonly ["If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.", "Use `allure agent` for smoke checks too, even when the change is small or mechanical.", "Only skip agent mode when it is impossible or when you are debugging agent mode itself.", "After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly."];
+export declare const AGENT_SMALL_TEST_CHANGE_WORKFLOW: readonly ["Create a fresh temp `ALLURE_AGENT_OUTPUT` and `ALLURE_AGENT_EXPECTATIONS` for the touched scope before closing the task.", "Run the touched scope with `allure agent`, even if the goal is only a smoke check after a mechanical change such as typing cleanup, mock refactors, or helper extraction.", "Review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` before making any final claim."];
 export declare const AGENT_COVERAGE_REVIEW_WORKFLOW: readonly ["Split package or business-logic audits into scoped groups and give each group its own temp output directory and expectations file.", "Review agent-mode artifacts first for each group, then inspect source code only after the runtime evidence shows what actually ran.", "Treat grouped coverage review as incomplete until each scoped run has matching expectations or an explicit note that the audit is intentionally broad."];
 export declare const AGENT_TEST_ENRICHMENT_BEST_PRACTICES: readonly ["Steps must wrap real actions, state transitions, or assertions. Prefer a small setup/action/assertion narrative over event-by-event step spam.", "Attachments must capture real runtime evidence from that execution: payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.", "Add metadata only when it improves scope review, debugging, or downstream policy. Keep labels and parameters intentionally minimal.", "If multiple call sites need the same evidence, instrument the helper once. Example: teach `runCommand` to emit a step instead of wrapping every `runCommand(...)` call site with identical step blocks."];
 export declare const AGENT_ANTI_DUMMY_POLICY: readonly ["Do not add empty wrapper steps, placeholder attachments, or generic strings such as `passed`, `success`, or static boilerplate.", "Do not attach evidence that is not grounded in the current test execution. Synthetic summaries are fine only when they are derived from real runtime artifacts.", "Do not inflate metadata with labels, stories, or severities that no expectation, review step, or policy actually uses."];
 export declare const AGENT_ACCEPTANCE_CHECKLIST: readonly ["The rerun matches the intended scope and does not trigger forbidden or unexpected-test findings.", "Each touched test shows enough evidence to explain what happened and what was verified.", "Retries include per-attempt diagnostics when the same test reruns.", "No high-confidence anti-dummy findings remain, especially `noop-dominated-steps` or low-signal `step-spam` traces."];
 export declare const AGENT_REVIEW_COMPLETENESS_CHECKLIST: readonly ["The relevant scope was run with agent mode unless that was impossible.", "Scoped reviews created expectations before the final rerun, unless the task was an intentionally broad package-health audit.", "The final conclusion was based on `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` rather than console output alone.", "Any missing or partial runtime modeling was called out explicitly before the review was considered complete."];
 export declare const AGENT_PARTIAL_RUNTIME_REVIEW_RULES: readonly ["Suite-load, import, or setup failures may appear only in `artifacts/global/stderr.txt` or global errors instead of `manifest/tests.jsonl`.", "If runner-visible failures are not represented as logical tests, inspect global stderr and treat the run as a partial runtime review, not a clean result set.", "Console-only conclusions stay provisional when agent output is missing, incomplete, or partially modeled."];
-export declare const AGENT_INSTRUCTIONS_TEMPLATE = "## Allure Agent Mode Instructions\n\n- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure run`. It preserves the original console logs and adds agent-mode artifacts when you need them.\n- Use `allure run` for smoke checks too, even when the change is small or mechanical.\n- Only skip agent mode when it is impossible or when you are debugging agent mode itself.\n- Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted rerun.\n- Run tests with `ALLURE_AGENT_OUTPUT` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.\n- Enrich only the intended tests. Add real steps for real setup, actions, and assertions.\n- Attach only real runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.\n- Keep metadata minimal. Add labels or severity only when scope review, debugging, or quality policy uses them.\n- Instrument stable helpers when several call sites need the same evidence. For example, teach `runCommand` to emit a step instead of wrapping every caller.\n- Reject the rerun if scope drifts, evidence stays weak, or high-confidence noop-style findings remain.";
+export declare const AGENT_INSTRUCTIONS_TEMPLATE = "## Allure Agent Mode Instructions\n\n- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.\n- Use `allure agent` for smoke checks too, even when the change is small or mechanical.\n- Only skip agent mode when it is impossible or when you are debugging agent mode itself.\n- After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly.\n- Use `ALLURE_AGENT_*` with `allure run` only as the lower-level fallback when you need direct environment control.\n- Use `allure agent latest` to reopen the newest run when `--output` was omitted.\n- Use `allure agent state-dir` to inspect where the current project stores its latest-agent state.\n- Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning.\n- Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests.\n- Use `--rerun-preset review|failed|unsuccessful|all`, repeated `--rerun-environment <id>`, and repeated `--rerun-label name=value` when you need a narrower rerun selection from the previous output.\n- Use `ALLURE_AGENT_STATE_DIR` when you need to override where the current project stores latest-agent state for `latest`, `state-dir`, or `--rerun-latest`.\n- Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted rerun.\n- Run tests with `allure agent` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.\n- Enrich only the intended tests. Add real steps for real setup, actions, and assertions.\n- Attach only real runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.\n- Keep metadata minimal. Add labels or severity only when scope review, debugging, or quality policy uses them.\n- Instrument stable helpers when several call sites need the same evidence. For example, teach `runCommand` to emit a step instead of wrapping every caller.\n- Reject the rerun if scope drifts, evidence stays weak, or high-confidence noop-style findings remain.";
 export declare const renderAgentsGuide: (projectGuidePath?: string) => string;

package/dist/guidance.js

@@ -112,19 +112,26 @@ export const ENRICHMENT_ACTIONS_BY_CHECK_NAME = {
 };
 export const AGENT_ENRICHMENT_WORKFLOW = [
     "Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted enrichment iteration.",
-    "Run tests with `allure run -- <command>` and `ALLURE_AGENT_OUTPUT` enabled.",
+    "Run tests with `allure agent --output <dir> --expectations <file> -- <command>`.",
+    "After each test run, print the `index.md` path from that output directory so collaborators can open the run overview quickly.",
+    "Use `allure agent latest` to recover the newest output directory when a prior run omitted `--output`.",
+    "Use `allure agent state-dir` to inspect where the current project stores its latest-agent state.",
+    "Use `ALLURE_AGENT_STATE_DIR` when you need to override where the current project stores latest-agent state for `latest`, `state-dir`, or `--rerun-latest`.",
+    "Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning.",
+    "Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests through Allure testplan support. Add `--rerun-preset`, repeated `--rerun-environment`, or repeated `--rerun-label name=value` filters when you need a narrower rerun slice.",
     "Inspect `manifest/run.json`, tail `manifest/test-events.jsonl`, then review `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` before editing tests.",
     "Enrich only the intended tests, rerun the same scope, and compare the rerun against `manifest/expected.json` when present.",
     "Accept the rerun only when scope is clean, evidence is strong enough to review, and no high-confidence dummy findings remain.",
 ];
 export const AGENT_VERIFICATION_RULES = [
-    "If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure run`. It preserves the original console logs and adds agent-mode artifacts when you need them.",
-    "Use `allure run` for smoke checks too, even when the change is small or mechanical.",
+    "If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.",
+    "Use `allure agent` for smoke checks too, even when the change is small or mechanical.",
     "Only skip agent mode when it is impossible or when you are debugging agent mode itself.",
+    "After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly.",
 ];
 export const AGENT_SMALL_TEST_CHANGE_WORKFLOW = [
     "Create a fresh temp `ALLURE_AGENT_OUTPUT` and `ALLURE_AGENT_EXPECTATIONS` for the touched scope before closing the task.",
-    "Run the touched scope with `allure run`, even if the goal is only a smoke check after a mechanical change such as typing cleanup, mock refactors, or helper extraction.",
+    "Run the touched scope with `allure agent`, even if the goal is only a smoke check after a mechanical change such as typing cleanup, mock refactors, or helper extraction.",
     "Review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` before making any final claim.",
 ];
 export const AGENT_COVERAGE_REVIEW_WORKFLOW = [
@@ -162,11 +169,19 @@ export const AGENT_PARTIAL_RUNTIME_REVIEW_RULES = [
 ];
 export const AGENT_INSTRUCTIONS_TEMPLATE = `## Allure Agent Mode Instructions
 
-- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through \`allure run\`. It preserves the original console logs and adds agent-mode artifacts when you need them.
-- Use \`allure run\` for smoke checks too, even when the change is small or mechanical.
+- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through \`allure agent\`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.
+- Use \`allure agent\` for smoke checks too, even when the change is small or mechanical.
 - Only skip agent mode when it is impossible or when you are debugging agent mode itself.
+- After each agent-mode test run, print the \`index.md\` path from that run's output directory so users can open the run overview quickly.
+- Use \`ALLURE_AGENT_*\` with \`allure run\` only as the lower-level fallback when you need direct environment control.
+- Use \`allure agent latest\` to reopen the newest run when \`--output\` was omitted.
+- Use \`allure agent state-dir\` to inspect where the current project stores its latest-agent state.
+- Use \`allure agent select --latest\` or \`allure agent select --from <output-dir>\` to inspect the review-targeted test plan before rerunning.
+- Use \`allure agent --rerun-latest -- <command>\` or \`allure agent --rerun-from <output-dir> -- <command>\` to rerun only the selected tests.
+- Use \`--rerun-preset review|failed|unsuccessful|all\`, repeated \`--rerun-environment <id>\`, and repeated \`--rerun-label name=value\` when you need a narrower rerun selection from the previous output.
+- Use \`ALLURE_AGENT_STATE_DIR\` when you need to override where the current project stores latest-agent state for \`latest\`, \`state-dir\`, or \`--rerun-latest\`.
 - Generate or refresh \`ALLURE_AGENT_EXPECTATIONS\` before each targeted rerun.
-- Run tests with \`ALLURE_AGENT_OUTPUT\` and review \`manifest/run.json\`, \`manifest/test-events.jsonl\`, \`index.md\`, \`manifest/tests.jsonl\`, and \`manifest/findings.jsonl\`.
+- Run tests with \`allure agent\` and review \`manifest/run.json\`, \`manifest/test-events.jsonl\`, \`index.md\`, \`manifest/tests.jsonl\`, and \`manifest/findings.jsonl\`.
 - Enrich only the intended tests. Add real steps for real setup, actions, and assertions.
 - Attach only real runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.
 - Keep metadata minimal. Add labels or severity only when scope review, debugging, or quality policy uses them.

package/dist/plugin.js

@@ -1446,7 +1446,7 @@ const buildRunAndTestFindings = (params) => {
             message: "The run does not include global stdout or stderr logs.",
             explanation: "Global process logs help agents debug bootstrap failures and compare the recorded results with console output.",
             evidencePaths: [],
-            remediationHint: "Run tests through `allure run -- <command>` without disabling log capture when you need bootstrap diagnostics.",
+            remediationHint: "Run tests through `allure agent -- <command>` without `--silent` when you need bootstrap diagnostics, or use `ALLURE_AGENT_*` with `allure run` for lower-level control.",
             confidence: 0.9,
         }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allurereport/plugin-agent",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Allure Agent Plugin – AI-friendly markdown report generator",
   "keywords": [
     "agent",
@@ -31,12 +31,12 @@
     "lint:fix": "oxlint --import-plugin --fix src test features stories"
   },
   "dependencies": {
-    "@allurereport/core-api": "3.5.0",
-    "@allurereport/plugin-api": "3.5.0",
+    "@allurereport/core-api": "3.6.0",
+    "@allurereport/plugin-api": "3.6.0",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@allurereport/reader-api": "3.5.0",
+    "@allurereport/reader-api": "3.6.0",
     "@types/node": "^20.17.9",
     "@vitest/runner": "^2.1.9",
     "allure-vitest": "^3.3.3",