allure 3.10.0 → 3.12.0

package/dist/commands/agent.js

@@ -1,53 +1,126 @@
 import * as console from "node:console";
-import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, realpath, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import process, { exit } from "node:process";
-import { AllureReport, isFileNotFoundError, readConfig } from "@allurereport/core";
+import { AGENT_FINDING_CATEGORIES, AGENT_FINDING_SEVERITIES, AGENT_TASK_MAP_HELP, AGENT_TEST_STATUSES, AgentExpectationUsageError, buildAgentInlineExpectations, buildAgentQueryPayload, cleanupAgentRunState, cleanupStaleAgentRunStates, createAgentCapabilities, formatAgentOutputLinks, isAgentExpectationUsageError, isAgentTaskMapHelpRequest, isAgentUsageError, loadAgentOutput, normalizeAgentQueryLimit, normalizeAgentQueryView, normalizeAgentRerunPreset, normalizeRepeatedEnumValues, normalizeRepeatedStringValues, parseAgentLabelFilters, readLatestAgentState, resolveAgentSelectionOutputDir, resolveAgentStateDir, selectAgentTestPlan, validateAgentExpectationsFile, writeAgentRunState, writeInvalidAgentExpectationOutput, } from "@allurereport/plugin-agent";
 import { Command, Option, UsageError } from "clipanion";
-import { createAgentTestPlanContext, normalizeAgentRerunPreset, parseAgentLabelFilters, resolveAgentSelectionOutputDir, selectAgentTestPlan, } from "../utils/agent-select.js";
-import { readLatestAgentState, resolveAgentStateDir, writeLatestAgentState } from "../utils/agent-state.js";
-import { environmentNameOption, environmentOption, normalizeCommandEnvironmentOptions, resolveCommandEnvironment, } from "../utils/environment.js";
-import { createChildAllureCliEnvironment, getActiveAllureCliCommand } from "../utils/execution-context.js";
-import { executeAllureRun, executeNestedAllureCommand } from "./commons/run.js";
-const withProcessEnv = async (overrides, fn) => {
-    const previousValues = new Map();
-    for (const [key, value] of Object.entries(overrides)) {
-        previousValues.set(key, process.env[key]);
-        if (value === undefined) {
-            delete process.env[key];
-            continue;
-        }
-        process.env[key] = value;
+export { AGENT_TASK_MAP_HELP, createAgentCapabilities, isAgentTaskMapHelpRequest };
+const readOptionalString = (value) => (typeof value === "string" ? value : undefined);
+const readOptionalBoolean = (value) => value === true;
+const readOptionalStringArray = (value) => (Array.isArray(value) ? value : undefined);
+const formatAgentCommand = (args) => args.join(" ");
+const AGENT_HUMAN_REPORT_MODES = ["auto", "off", "awesome", "config"];
+const formatAgentInspectCommand = (params) => [
+    "allure",
+    "agent",
+    "inspect",
+    ...(params.dumps ?? []).flatMap((dump) => ["--dump", dump]),
+    ...(params.resultsDir ?? []),
+].join(" ");
+const buildInlineExpectationsFromOptions = (options) => buildAgentInlineExpectations({
+    goal: options.goal,
+    taskId: options.taskId,
+    expectTests: options.expectTests,
+    expectLabels: readOptionalStringArray(options.expectLabels),
+    expectEnvironments: readOptionalStringArray(options.expectEnvironments),
+    expectFullNames: readOptionalStringArray(options.expectFullNames),
+    expectPrefixes: readOptionalStringArray(options.expectPrefixes),
+    forbidLabels: readOptionalStringArray(options.forbidLabels),
+    expectStepContains: readOptionalStringArray(options.expectStepContains),
+    expectSteps: options.expectSteps,
+    expectAttachments: options.expectAttachments,
+    expectAttachmentFilters: readOptionalStringArray(options.expectAttachmentFilters),
+});
+const printAgentOutputLinks = (outputDir) => {
+    for (const line of formatAgentOutputLinks(outputDir)) {
+        console.log(line);
     }
+};
+const persistAgentRunState = async (value) => {
     try {
-        return await fn();
+        await writeAgentRunState(value);
     }
-    finally {
-        for (const [key, value] of previousValues) {
-            if (value === undefined) {
-                delete process.env[key];
-                continue;
-            }
-            process.env[key] = value;
-        }
+    catch (error) {
+        console.error(`Could not update agent state in ${resolveAgentStateDir(value.cwd)}: ${error.message}`);
+    }
+};
+const logAgentCleanupFailures = (failures) => {
+    for (const failure of failures) {
+        console.error(`Could not clean stale agent output ${failure.state.outputDir}: ${failure.error.message}`);
     }
 };
-const isPathInside = (parentPath, candidatePath) => {
-    const rel = relative(parentPath, candidatePath);
-    return rel === "" || (!rel.startsWith("..") && rel !== "." && !rel.startsWith("../"));
+const logAgentOrphanCleanupFailures = (failures) => {
+    for (const failure of failures) {
+        console.error(`Could not clean stale agent output ${failure.outputDir}: ${failure.error.message}`);
+    }
 };
-const persistLatestAgentState = async (value) => {
+const cleanupManagedAgentOutputs = async (params) => {
     try {
-        await writeLatestAgentState(value);
+        const result = await cleanupAgentRunState({
+            cwd: params.cwd,
+            currentRunId: params.runId,
+            keepManagedRuns: params.managedOutput ? 1 : 0,
+        });
+        logAgentCleanupFailures(result.failed);
     }
     catch (error) {
-        console.error(`Could not update latest agent output in ${resolveAgentStateDir(value.cwd)}: ${error.message}`);
+        console.error(`Could not clean agent state in ${resolveAgentStateDir(params.cwd)}: ${error.message}`);
+    }
+    try {
+        const staleResult = await cleanupStaleAgentRunStates({
+            cwd: params.cwd,
+            currentRunId: params.runId,
+        });
+        logAgentCleanupFailures(staleResult.failed);
+        logAgentOrphanCleanupFailures(staleResult.orphaned.failed);
+    }
+    catch (error) {
+        console.error(`Could not clean agent state in ${resolveAgentStateDir(params.cwd)}: ${error.message}`);
     }
 };
-const readOptionalString = (value) => (typeof value === "string" ? value : undefined);
-const readOptionalBoolean = (value) => value === true;
-const readOptionalStringArray = (value) => (Array.isArray(value) ? value : undefined);
+const agentEnvironmentOption = () => Option.String("--environment,--env", {
+    description: "Force specific environment ID to all tests in the run. Given environment has higher priority than the one defined in the config file (default: empty string)",
+});
+const agentEnvironmentNameOption = () => Option.String("--environment-name", {
+    description: "Force specific environment display name to all tests in the run. Has lower priority than --environment and higher than the config value (default: empty string)",
+});
+const throwCliUsageError = (error) => {
+    if (isAgentUsageError(error)) {
+        throw new UsageError(error.message);
+    }
+    throw error;
+};
+const normalizeAgentHumanReportMode = (value) => {
+    if (value === undefined) {
+        return "auto";
+    }
+    if (AGENT_HUMAN_REPORT_MODES.includes(value)) {
+        return value;
+    }
+    throw new UsageError(`Unsupported --report mode ${JSON.stringify(value)}. Use auto, off, awesome, or config.`);
+};
+export class AgentCapabilitiesCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.json = Option.Boolean("--json", true, {
+            description: "Print capabilities as JSON (default: true)",
+        });
+    }
+    async execute() {
+        console.log(JSON.stringify(createAgentCapabilities(), null, 2));
+    }
+}
+AgentCapabilitiesCommand.paths = [["agent", "capabilities"]];
+AgentCapabilitiesCommand.usage = Command.Usage({
+    description: "Print structured Allure agent capability information",
+    details: "This command prints the locally supported agent-mode commands, expectation controls, output files, rerun support, and known unsupported capability families as JSON.",
+    examples: [
+        ["agent capabilities", "Print agent capabilities as JSON"],
+        ["agent capabilities --json", "Print agent capabilities as JSON explicitly"],
+    ],
+});
 export class AgentCommand extends Command {
     constructor() {
         super(...arguments);
@@ -58,13 +131,52 @@ export class AgentCommand extends Command {
             description: "The working directory for the command to run (default: current working directory)",
         });
         this.output = Option.String("--output,-o", {
-            description: "The output directory for agent artifacts. Absolute paths are accepted as well",
+            description: "The output directory for agent artifacts. Absolute paths are accepted. Explicit output is caller-managed; remove or archive it when no longer needed so later state compaction can drop its record",
+        });
+        this.report = Option.String("--report", {
+            description: "Human report mode: auto, off, awesome, or config. Auto writes awesome/index.html for 1000 or fewer stored visible results and records manifest/human-report.json (default: auto)",
         });
         this.expectations = Option.String("--expectations", {
             description: "The path to a YAML or JSON expectations file",
         });
-        this.environment = environmentOption();
-        this.environmentName = environmentNameOption();
+        this.goal = Option.Array("--goal", {
+            description: "The review goal to record in inline agent expectations",
+        });
+        this.taskId = Option.Array("--task-id", {
+            description: "The task or feature id to record in inline agent expectations",
+        });
+        this.expectTests = Option.Array("--expect-tests", {
+            description: "The expected number of visible logical tests in the intended scope",
+        });
+        this.expectLabels = Option.Array("--expect-label", {
+            description: "Expected label selector in name=value form. Repeat the option for multiple selectors",
+        });
+        this.expectEnvironments = Option.Array("--expect-env", {
+            description: "Expected environment id. Repeat the option for multiple environments",
+        });
+        this.expectFullNames = Option.Array("--expect-test", {
+            description: "Expected full test name. Repeat the option for multiple tests",
+        });
+        this.expectPrefixes = Option.Array("--expect-prefix", {
+            description: "Expected full-name prefix. Repeat the option for multiple prefixes",
+        });
+        this.forbidLabels = Option.Array("--forbid-label", {
+            description: "Forbidden label selector in name=value form. Repeat the option for multiple selectors",
+        });
+        this.expectStepContains = Option.Array("--expect-step-containing", {
+            description: "Require a test-scoped step name containing this text per evidence-target logical test",
+        });
+        this.expectSteps = Option.Array("--expect-steps", {
+            description: "Require at least this many meaningful steps per expected logical test",
+        });
+        this.expectAttachments = Option.Array("--expect-attachments", {
+            description: "Require at least this many non-missing attachments per expected logical test",
+        });
+        this.expectAttachmentFilters = Option.Array("--expect-attachment", {
+            description: "Require a matching non-missing attachment per expected logical test. Use a file name or name=value/content-type=value",
+        });
+        this.environment = agentEnvironmentOption();
+        this.environmentName = agentEnvironmentNameOption();
         this.silent = Option.Boolean("--silent", {
             description: "Don't pipe the process output logs to console (default: false)",
         });
@@ -87,35 +199,295 @@ export class AgentCommand extends Command {
     }
     async execute() {
         const args = this.commandToRun.filter((arg) => arg !== "--");
-        await executeAgentMode({
-            configPath: readOptionalString(this.config),
-            cwd: readOptionalString(this.cwd),
-            output: readOptionalString(this.output),
-            expectations: readOptionalString(this.expectations),
-            environment: readOptionalString(this.environment),
-            environmentName: readOptionalString(this.environmentName),
-            silent: readOptionalBoolean(this.silent),
-            rerunFrom: readOptionalString(this.rerunFrom),
-            rerunLatest: readOptionalBoolean(this.rerunLatest),
-            rerunPreset: readOptionalString(this.rerunPreset),
-            rerunEnvironments: readOptionalStringArray(this.rerunEnvironments),
-            rerunLabels: readOptionalStringArray(this.rerunLabels),
-            args,
-        });
+        const configPath = readOptionalString(this.config);
+        const configuredCwd = readOptionalString(this.cwd);
+        const output = readOptionalString(this.output);
+        const reportMode = normalizeAgentHumanReportMode(readOptionalString(this.report));
+        const expectations = readOptionalString(this.expectations);
+        if (!args.length) {
+            throw new UsageError("expecting command to be specified after --, e.g. allure agent -- npm run test");
+        }
+        try {
+            const inlineExpectations = buildInlineExpectationsFromOptions({
+                goal: this.goal,
+                taskId: this.taskId,
+                expectTests: this.expectTests,
+                expectLabels: this.expectLabels,
+                expectEnvironments: this.expectEnvironments,
+                expectFullNames: this.expectFullNames,
+                expectPrefixes: this.expectPrefixes,
+                forbidLabels: this.forbidLabels,
+                expectStepContains: this.expectStepContains,
+                expectSteps: this.expectSteps,
+                expectAttachments: this.expectAttachments,
+                expectAttachmentFilters: this.expectAttachmentFilters,
+            });
+            if (expectations && inlineExpectations) {
+                throw new AgentExpectationUsageError("Use either --expectations <file> or inline expectation flags, not both", "--expectations");
+            }
+            await validateAgentExpectationsFile({
+                cwd: await realpath(configuredCwd ?? process.cwd()),
+                output,
+                expectations,
+            });
+            const { executeAgentMode } = await import("./agent-run.js");
+            await executeAgentMode({
+                configPath,
+                cwd: configuredCwd,
+                output,
+                expectations,
+                inlineExpectations: inlineExpectations,
+                environment: readOptionalString(this.environment),
+                environmentName: readOptionalString(this.environmentName),
+                silent: readOptionalBoolean(this.silent),
+                rerunFrom: readOptionalString(this.rerunFrom),
+                rerunLatest: readOptionalBoolean(this.rerunLatest),
+                rerunPreset: readOptionalString(this.rerunPreset),
+                rerunEnvironments: readOptionalStringArray(this.rerunEnvironments),
+                rerunLabels: readOptionalStringArray(this.rerunLabels),
+                reportMode,
+                args,
+            });
+        }
+        catch (error) {
+            if (!isAgentExpectationUsageError(error)) {
+                throwCliUsageError(error);
+            }
+            const expectationError = error;
+            const cwd = await realpath(configuredCwd ?? process.cwd());
+            const runId = randomUUID();
+            const managedOutput = !output;
+            const outputDir = output ? resolve(cwd, output) : await mkdtemp(join(tmpdir(), "allure-agent-"));
+            const commandString = formatAgentCommand(args);
+            const { generatedAt } = await writeInvalidAgentExpectationOutput({
+                outputDir,
+                command: commandString,
+                error: expectationError,
+            });
+            const generatedAtMs = Date.parse(generatedAt);
+            const generatedAtTimestamp = Number.isFinite(generatedAtMs) ? generatedAtMs : Date.now();
+            await persistAgentRunState({
+                runId,
+                cwd,
+                outputDir,
+                managedOutput,
+                command: commandString,
+                startedAt: generatedAtTimestamp,
+                finishedAt: generatedAtTimestamp,
+                status: "finished",
+                exitCode: 1,
+                pid: process.pid,
+            });
+            await cleanupManagedAgentOutputs({ cwd, runId, managedOutput });
+            printAgentOutputLinks(outputDir);
+            console.error(expectationError.message);
+            exit(1);
+        }
     }
 }
 AgentCommand.paths = [["agent"]];
 AgentCommand.usage = Command.Usage({
     description: "Run specified command in Allure agent mode",
-    details: "This command runs the specified command with an agent-only Allure profile.",
+    details: "This command runs the specified command with an agent-mode Allure profile and optional human-readable report output. With the default --report auto mode, runs with 1000 or fewer stored visible logical results also write a single-file Awesome report at <output>/awesome/index.html and record its status in <output>/manifest/human-report.json. If a user asks for the report after a run, use `allure agent latest` to recover the output directory and check the human-report manifest before regenerating anything.",
     examples: [
-        ["agent -- npm test", "Run npm test and capture only the agent-mode output"],
+        ["agent -- npm test", "Run npm test and capture agent-mode output with the default human report policy"],
+        ["agent --report off -- npm test", "Run npm test and capture only the agent-mode artifacts"],
         [
             "agent --expectations ./expected.yaml -- npm test",
             "Run npm test with agent-mode expectations loaded from ./expected.yaml",
         ],
     ],
 });
+export class AgentInspectCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.resultsDir = Option.Rest({
+            name: "Patterns to match test results directories in the current working directory (default: ./**/allure-results)",
+        });
+        this.config = Option.String("--config,-c", {
+            description: "The path Allure config file",
+        });
+        this.cwd = Option.String("--cwd", {
+            description: "The working directory for resolving results and dumps (default: current working directory)",
+        });
+        this.output = Option.String("--output,-o", {
+            description: "The output directory for agent artifacts. Absolute paths are accepted. Explicit output is caller-managed; remove or archive it when no longer needed so later state compaction can drop its record",
+        });
+        this.report = Option.String("--report", {
+            description: "Human report mode: auto, off, awesome, or config. Auto writes awesome/index.html for 1000 or fewer stored visible results and records manifest/human-report.json (default: auto)",
+        });
+        this.reportName = Option.String("--report-name,--name", {
+            description: "The report name to pass through configuration defaults (default: Allure Report)",
+        });
+        this.dump = Option.Array("--dump", {
+            description: "Path or pattern that matches one or more archives created by `allure run --dump ...`. " +
+                "This option can be specified multiple times.",
+        });
+        this.open = Option.Boolean("--open", {
+            description: "Accepted for parity with generate. Agent inspect writes agent artifacts and prints their paths",
+        });
+        this.port = Option.String("--port", {
+            description: "Accepted for parity with generate. Agent inspect doesn't serve the output",
+        });
+        this.historyLimit = Option.String("--history-limit", {
+            description: "Limits the number of history entries to keep (default: unlimited)",
+        });
+        this.hideLabels = Option.Array("--hide-labels", {
+            description: "Hide labels by exact name in generated data. Repeat the option for multiple labels",
+        });
+        this.expectations = Option.String("--expectations", {
+            description: "The path to a YAML or JSON expectations file",
+        });
+        this.goal = Option.Array("--goal", {
+            description: "The review goal to record in inline agent expectations",
+        });
+        this.taskId = Option.Array("--task-id", {
+            description: "The task or feature id to record in inline agent expectations",
+        });
+        this.expectTests = Option.Array("--expect-tests", {
+            description: "The expected number of visible logical tests in the intended scope",
+        });
+        this.expectLabels = Option.Array("--expect-label", {
+            description: "Expected label selector in name=value form. Repeat the option for multiple selectors",
+        });
+        this.expectEnvironments = Option.Array("--expect-env", {
+            description: "Expected environment id. Repeat the option for multiple environments",
+        });
+        this.expectFullNames = Option.Array("--expect-test", {
+            description: "Expected full test name. Repeat the option for multiple tests",
+        });
+        this.expectPrefixes = Option.Array("--expect-prefix", {
+            description: "Expected full-name prefix. Repeat the option for multiple prefixes",
+        });
+        this.forbidLabels = Option.Array("--forbid-label", {
+            description: "Forbidden label selector in name=value form. Repeat the option for multiple selectors",
+        });
+        this.expectStepContains = Option.Array("--expect-step-containing", {
+            description: "Require a test-scoped step name containing this text per evidence-target logical test",
+        });
+        this.expectSteps = Option.Array("--expect-steps", {
+            description: "Require at least this many meaningful steps per expected logical test",
+        });
+        this.expectAttachments = Option.Array("--expect-attachments", {
+            description: "Require at least this many non-missing attachments per expected logical test",
+        });
+        this.expectAttachmentFilters = Option.Array("--expect-attachment", {
+            description: "Require a matching non-missing attachment per expected logical test. Use a file name or name=value/content-type=value",
+        });
+        this.environment = agentEnvironmentOption();
+        this.environmentName = agentEnvironmentNameOption();
+    }
+    async execute() {
+        const configPath = readOptionalString(this.config);
+        const configuredCwd = readOptionalString(this.cwd);
+        const output = readOptionalString(this.output);
+        const reportMode = normalizeAgentHumanReportMode(readOptionalString(this.report));
+        const dumps = readOptionalStringArray(this.dump) ?? [];
+        const resultsDir = this.resultsDir;
+        const expectations = readOptionalString(this.expectations);
+        if (resultsDir.includes("--")) {
+            throw new UsageError("agent inspect does not run commands; pass result directories directly, e.g. allure agent inspect ./allure-results");
+        }
+        try {
+            const inlineExpectations = buildInlineExpectationsFromOptions({
+                goal: this.goal,
+                taskId: this.taskId,
+                expectTests: this.expectTests,
+                expectLabels: this.expectLabels,
+                expectEnvironments: this.expectEnvironments,
+                expectFullNames: this.expectFullNames,
+                expectPrefixes: this.expectPrefixes,
+                forbidLabels: this.forbidLabels,
+                expectStepContains: this.expectStepContains,
+                expectSteps: this.expectSteps,
+                expectAttachments: this.expectAttachments,
+                expectAttachmentFilters: this.expectAttachmentFilters,
+            });
+            if (expectations && inlineExpectations) {
+                throw new AgentExpectationUsageError("Use either --expectations <file> or inline expectation flags, not both", "--expectations");
+            }
+            await validateAgentExpectationsFile({
+                cwd: await realpath(configuredCwd ?? process.cwd()),
+                output,
+                expectations,
+            });
+            const { executeAgentInspectMode } = await import("./agent-run.js");
+            await executeAgentInspectMode({
+                configPath,
+                cwd: configuredCwd,
+                output,
+                expectations,
+                inlineExpectations: inlineExpectations,
+                environment: readOptionalString(this.environment),
+                environmentName: readOptionalString(this.environmentName),
+                reportName: readOptionalString(this.reportName),
+                open: readOptionalBoolean(this.open),
+                port: readOptionalString(this.port),
+                historyLimit: readOptionalString(this.historyLimit),
+                hideLabels: readOptionalStringArray(this.hideLabels),
+                dumps,
+                reportMode,
+                resultsDir,
+            });
+        }
+        catch (error) {
+            if (!isAgentExpectationUsageError(error)) {
+                throwCliUsageError(error);
+            }
+            const expectationError = error;
+            const cwd = await realpath(configuredCwd ?? process.cwd());
+            const runId = randomUUID();
+            const managedOutput = !output;
+            const outputDir = output ? resolve(cwd, output) : await mkdtemp(join(tmpdir(), "allure-agent-"));
+            const commandString = formatAgentInspectCommand({ dumps, resultsDir });
+            const { generatedAt } = await writeInvalidAgentExpectationOutput({
+                outputDir,
+                command: commandString,
+                error: expectationError,
+            });
+            const generatedAtMs = Date.parse(generatedAt);
+            const generatedAtTimestamp = Number.isFinite(generatedAtMs) ? generatedAtMs : Date.now();
+            await persistAgentRunState({
+                runId,
+                cwd,
+                outputDir,
+                managedOutput,
+                command: commandString,
+                startedAt: generatedAtTimestamp,
+                finishedAt: generatedAtTimestamp,
+                status: "finished",
+                exitCode: 1,
+                pid: process.pid,
+            });
+            await cleanupManagedAgentOutputs({ cwd, runId, managedOutput });
+            printAgentOutputLinks(outputDir);
+            console.error(expectationError.message);
+            exit(1);
+        }
+    }
+}
+AgentInspectCommand.paths = [["agent", "inspect"]];
+AgentInspectCommand.usage = Command.Usage({
+    description: "Inspect existing Allure results or dump archives in Allure agent mode",
+    details: "This command restores dump archives and reads existing Allure results directories, then writes agent-mode output and optional human-readable report output without running a test command. With the default --report auto mode, inputs with 1000 or fewer stored visible logical results also write a single-file Awesome report at <output>/awesome/index.html and record its status in <output>/manifest/human-report.json. If a user asks for the report after an inspect run, use `allure agent latest` to recover the output directory and check the human-report manifest before regenerating anything.",
+    examples: [
+        ["agent inspect ./allure-results", "Inspect an existing Allure results directory"],
+        ["agent inspect ./packages/*/out/allure-results", "Inspect matching Allure results directories"],
+        ["agent inspect --dump allure-results-linux.zip", "Inspect a dump archive downloaded from CI"],
+        [
+            "agent inspect --dump allure-results-linux.zip --dump allure-results-macos.zip",
+            "Inspect multiple CI dump archives together",
+        ],
+        [
+            "agent inspect --dump allure-results-linux.zip ./local/allure-results",
+            "Inspect dump archives together with local results directories",
+        ],
+        [
+            "agent inspect --config ./allurerc.mjs --output ./agent-output ./allure-results",
+            "Inspect existing results with a config file and write agent artifacts to ./agent-output",
+        ],
+    ],
+});
 export class AgentLatestCommand extends Command {
     constructor() {
         super(...arguments);
@@ -139,16 +511,19 @@ export class AgentLatestCommand extends Command {
             exit(1);
             return;
         }
-        console.log(latestState.outputDir);
+        printAgentOutputLinks(latestState.outputDir);
     }
 }
 AgentLatestCommand.paths = [["agent", "latest"]];
 AgentLatestCommand.usage = Command.Usage({
-    description: "Print the latest Allure agent output directory for the current project",
-    details: "This command prints the latest agent output directory recorded for the resolved project cwd.",
+    description: "Print the latest Allure agent output directory and index path for the current project",
+    details: "This command prints the latest agent output directory and index.md path recorded for the resolved project cwd. When a user asks for a human-readable report from the last run, use this output directory to check manifest/human-report.json; if its status is generated, the report path is relative to that same output directory, usually awesome/index.html.",
     examples: [
-        ["agent latest", "Print the latest agent output directory for the current project"],
-        ["agent latest --cwd ./packages/cli", "Print the latest agent output directory for a specific project cwd"],
+        ["agent latest", "Print the latest agent output directory and index path for the current project"],
+        [
+            "agent latest --cwd ./packages/cli",
+            "Print the latest agent output directory and index path for a specific project cwd",
+        ],
     ],
 });
 export class AgentStateDirCommand extends Command {
@@ -165,11 +540,100 @@ export class AgentStateDirCommand extends Command {
 }
 AgentStateDirCommand.paths = [["agent", "state-dir"]];
 AgentStateDirCommand.usage = Command.Usage({
-    description: "Print the Allure agent state directory for the current project",
-    details: "This command prints the resolved state directory used to persist latest-agent pointers for the current project cwd.",
+    description: "Print the shared Allure agent state directory",
+    details: "This command prints the resolved state directory used to persist per-project agent run registries.",
     examples: [
-        ["agent state-dir", "Print the resolved state directory for the current project"],
-        ["agent state-dir --cwd ./packages/cli", "Print the resolved state directory for a specific project cwd"],
+        ["agent state-dir", "Print the resolved shared state directory"],
+        ["agent state-dir --cwd ./packages/cli", "Print the shared state directory using a specific project cwd"],
+    ],
+});
+export class AgentQueryCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.view = Option.String({
+            required: false,
+            name: "Query view: summary, tests, findings, or test (default: summary)",
+        });
+        this.cwd = Option.String("--cwd", {
+            description: "The project directory used to resolve --latest and relative paths (default: current working directory)",
+        });
+        this.from = Option.String("--from", {
+            description: "The prior agent output directory to query",
+        });
+        this.latest = Option.Boolean("--latest", {
+            description: "Use the latest recorded agent output for the current project cwd",
+        });
+        this.statuses = Option.Array("--status", {
+            description: "Filter tests by status: failed, broken, unknown, skipped, or passed. Repeat for multiple statuses",
+        });
+        this.environments = Option.Array("--environment", {
+            description: "Filter tests by environment id. Repeat the option for multiple environments",
+        });
+        this.labels = Option.Array("--label", {
+            description: "Filter tests by exact label name=value. Repeat the option for multiple filters",
+        });
+        this.severities = Option.Array("--severity", {
+            description: "Filter findings by severity: high, warning, or info. Repeat for multiple severities",
+        });
+        this.categories = Option.Array("--category", {
+            description: "Filter findings by category. Repeat the option for multiple categories",
+        });
+        this.checks = Option.Array("--check", {
+            description: "Filter findings by check name. Repeat the option for multiple checks",
+        });
+        this.test = Option.String("--test", {
+            description: "Filter to one test by full name, test result id, history id, or markdown path",
+        });
+        this.limit = Option.String("--limit", {
+            description: "Limit returned tests or findings to this non-negative count",
+        });
+        this.includeMarkdown = Option.Boolean("--include-markdown", {
+            description: "Include the per-test markdown content for the test view",
+        });
+    }
+    async execute() {
+        try {
+            const cwd = await realpath(readOptionalString(this.cwd) ?? process.cwd());
+            const view = normalizeAgentQueryView(readOptionalString(this.view));
+            const outputDir = await resolveAgentSelectionOutputDir({
+                cwd,
+                from: readOptionalString(this.from),
+                latest: readOptionalBoolean(this.latest),
+            });
+            const output = await loadAgentOutput(outputDir);
+            const payload = await buildAgentQueryPayload(output, view, {
+                environments: normalizeRepeatedStringValues(readOptionalStringArray(this.environments)),
+                labelFilters: parseAgentLabelFilters(readOptionalStringArray(this.labels)),
+                statuses: normalizeRepeatedEnumValues(readOptionalStringArray(this.statuses), AGENT_TEST_STATUSES, "--status"),
+                severities: normalizeRepeatedEnumValues(readOptionalStringArray(this.severities), AGENT_FINDING_SEVERITIES, "--severity"),
+                categories: normalizeRepeatedEnumValues(readOptionalStringArray(this.categories), AGENT_FINDING_CATEGORIES, "--category"),
+                checks: normalizeRepeatedStringValues(readOptionalStringArray(this.checks)),
+                test: readOptionalString(this.test),
+                limit: normalizeAgentQueryLimit(readOptionalString(this.limit)),
+                includeMarkdown: readOptionalBoolean(this.includeMarkdown),
+            });
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        catch (error) {
+            throwCliUsageError(error);
+        }
+    }
+}
+AgentQueryCommand.paths = [["agent", "query"]];
+AgentQueryCommand.usage = Command.Usage({
+    description: "Query an existing Allure agent output directory as focused JSON",
+    details: "This command reads a prior agent output directory and prints focused JSON for a run summary, test list, findings list, or one test. Use --latest to query the latest recorded output for the project, or --from to query a specific output directory.",
+    examples: [
+        ["agent query --latest summary", "Print a summary for the latest agent output"],
+        ["agent query --from ./out/agent-output tests --status failed", "List failed tests from a prior output"],
+        [
+            "agent query --from ./out/agent-output findings --severity high",
+            "List high-severity findings from a prior output",
+        ],
+        [
+            'agent query --latest test --test "suite should pass" --include-markdown',
+            "Print one test summary with its per-test markdown",
+        ],
     ],
 });
 export class AgentSelectCommand extends Command {
@@ -198,177 +662,52 @@ export class AgentSelectCommand extends Command {
         });
     }
     async execute() {
-        const cwd = await realpath(readOptionalString(this.cwd) ?? process.cwd());
-        const environments = readOptionalStringArray(this.environments);
-        const labels = readOptionalStringArray(this.labels);
-        const outputDir = await resolveAgentSelectionOutputDir({
-            cwd,
-            from: readOptionalString(this.from),
-            latest: readOptionalBoolean(this.latest),
-        });
-        const selection = await selectAgentTestPlan({
-            outputDir,
-            preset: normalizeAgentRerunPreset(readOptionalString(this.preset)),
-            environments: environments?.length ? environments : undefined,
-            labelFilters: parseAgentLabelFilters(labels),
-        });
-        if (!selection.testPlan.tests.length) {
-            console.error(`No tests matched selection in ${selection.outputDir}`);
-            exit(1);
-            return;
+        try {
+            const cwd = await realpath(readOptionalString(this.cwd) ?? process.cwd());
+            const environments = readOptionalStringArray(this.environments);
+            const labels = readOptionalStringArray(this.labels);
+            const outputDir = await resolveAgentSelectionOutputDir({
+                cwd,
+                from: readOptionalString(this.from),
+                latest: readOptionalBoolean(this.latest),
+            });
+            const selection = await selectAgentTestPlan({
+                outputDir,
+                preset: normalizeAgentRerunPreset(readOptionalString(this.preset)),
+                environments: environments?.length ? environments : undefined,
+                labelFilters: parseAgentLabelFilters(labels),
+            });
+            if (!selection.testPlan.tests.length) {
+                console.error(`No tests matched selection in ${selection.outputDir}`);
+                exit(1);
+                return;
+            }
+            const serialized = `${JSON.stringify(selection.testPlan, null, 2)}\n`;
+            const output = readOptionalString(this.output);
+            if (!output) {
+                console.log(serialized.trimEnd());
+                return;
+            }
+            const outputPath = resolve(cwd, output);
+            await mkdir(dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, serialized, "utf-8");
+            console.log(`agent testplan: ${outputPath}`);
+            console.log(`agent selection source: ${selection.outputDir}`);
+            console.log(`agent selection preset: ${selection.preset}`);
+            console.log(`agent selection tests: ${selection.selectedTests.length}`);
         }
-        const serialized = `${JSON.stringify(selection.testPlan, null, 2)}\n`;
-        const output = readOptionalString(this.output);
-        if (!output) {
-            console.log(serialized.trimEnd());
-            return;
+        catch (error) {
+            throwCliUsageError(error);
         }
-        const outputPath = resolve(cwd, output);
-        await mkdir(dirname(outputPath), { recursive: true });
-        await writeFile(outputPath, serialized, "utf-8");
-        console.log(outputPath);
     }
 }
 AgentSelectCommand.paths = [["agent", "select"]];
 AgentSelectCommand.usage = Command.Usage({
     description: "Select tests from an existing agent output and emit a test plan",
-    details: "This command resolves a set of tests from a prior agent run and prints or writes a testplan.json payload.",
+    details: "This command resolves a set of tests from a prior agent run and prints or writes a testplan.json payload. When --output is used, stdout contains the written test plan path, source output directory, preset, and selected test count.",
     examples: [
         ["agent select --from ./out/agent-output", "Print a test plan for the default review-targeted tests"],
         ["agent select --latest --preset failed", "Print a test plan for failed tests from the latest project run"],
         ["agent select --from ./out/agent-output --output ./testplan.json", "Write the selected test plan to a file"],
     ],
 });
-export const executeAgentMode = async (params) => {
-    const { configPath, cwd: configuredCwd, output, expectations, environment, environmentName, silent, rerunFrom, rerunLatest, rerunPreset, rerunEnvironments, rerunLabels, args, } = params;
-    if (!args || !args.length) {
-        throw new UsageError("expecting command to be specified after --, e.g. allure agent -- npm run test");
-    }
-    const command = args[0];
-    const commandArgs = args.slice(1);
-    const cwd = await realpath(configuredCwd ?? process.cwd());
-    const commandString = `${command} ${commandArgs.join(" ")}`;
-    const hasRerunSource = !!rerunFrom || !!rerunLatest;
-    const hasRerunFilters = !!rerunPreset || !!rerunEnvironments?.length || !!rerunLabels?.length;
-    if (!hasRerunSource && hasRerunFilters) {
-        throw new UsageError("Use rerun filters only together with --rerun-from <path> or --rerun-latest");
-    }
-    const rerunContext = await createAgentTestPlanContext({
-        cwd,
-        from: rerunFrom,
-        latest: rerunLatest,
-        preset: normalizeAgentRerunPreset(rerunPreset),
-        environments: rerunEnvironments?.length ? rerunEnvironments : undefined,
-        labelFilters: parseAgentLabelFilters(rerunLabels),
-    });
-    const childEnvironmentVariables = {
-        ...createChildAllureCliEnvironment("agent"),
-        ...(rerunContext ? { ALLURE_TESTPLAN_PATH: rerunContext.testPlanPath } : {}),
-    };
-    try {
-        if (getActiveAllureCliCommand()) {
-            console.log(commandString);
-            const exitCode = await executeNestedAllureCommand({
-                command,
-                commandArgs,
-                cwd,
-                ...(rerunContext ? { environmentVariables: { ALLURE_TESTPLAN_PATH: rerunContext.testPlanPath } } : {}),
-                silent,
-            });
-            exit(exitCode ?? -1);
-            return;
-        }
-        const outputDir = output ? resolve(cwd, output) : await mkdtemp(join(tmpdir(), "allure-agent-"));
-        const expectationsPath = expectations ? resolve(cwd, expectations) : undefined;
-        const environmentOptions = {
-            environment,
-            environmentName,
-        };
-        normalizeCommandEnvironmentOptions(environmentOptions);
-        if (expectationsPath && isPathInside(outputDir, expectationsPath)) {
-            throw new UsageError(`--expectations path ${JSON.stringify(expectationsPath)} must not be inside the agent output directory ${JSON.stringify(outputDir)}`);
-        }
-        const config = await readConfig(cwd, configPath, {
-            output: outputDir,
-            plugins: {
-                agent: {
-                    options: {
-                        outputDir,
-                    },
-                },
-            },
-        });
-        const resolvedEnvironment = resolveCommandEnvironment(config, environmentOptions);
-        try {
-            await rm(outputDir, { recursive: true });
-        }
-        catch (error) {
-            if (!isFileNotFoundError(error)) {
-                console.error("could not clean output directory", error);
-            }
-        }
-        const startedAt = new Date().toISOString();
-        await persistLatestAgentState({
-            cwd,
-            outputDir,
-            expectationsPath,
-            command: commandString,
-            startedAt,
-            status: "running",
-        });
-        console.log(`agent output: ${outputDir}`);
-        if (expectationsPath) {
-            console.log(`agent expectations: ${expectationsPath}`);
-        }
-        console.log(commandString);
-        const allureReport = new AllureReport({
-            ...config,
-            output: outputDir,
-            environment: resolvedEnvironment?.id,
-            open: false,
-            port: undefined,
-            qualityGate: undefined,
-            allureService: undefined,
-            realTime: false,
-            plugins: config.plugins,
-        });
-        const knownIssues = await allureReport.store.allKnownIssues();
-        const { globalExitCode } = await withProcessEnv({
-            ALLURE_AGENT_OUTPUT: outputDir,
-            ALLURE_AGENT_EXPECTATIONS: expectationsPath,
-            ALLURE_AGENT_COMMAND: commandString,
-            ALLURE_AGENT_PROJECT_ROOT: cwd,
-            ALLURE_AGENT_NAME: undefined,
-            ALLURE_AGENT_LOOP_ID: undefined,
-            ALLURE_AGENT_TASK_ID: undefined,
-            ALLURE_AGENT_CONVERSATION_ID: undefined,
-        }, async () => await executeAllureRun({
-            allureReport,
-            knownIssues,
-            cwd,
-            command,
-            commandArgs,
-            environmentVariables: childEnvironmentVariables,
-            environment: resolvedEnvironment?.id,
-            withQualityGate: false,
-            logs: "pipe",
-            silent,
-            ignoreLogs: false,
-            logProcessExit: false,
-        }));
-        await persistLatestAgentState({
-            cwd,
-            outputDir,
-            expectationsPath,
-            command: commandString,
-            startedAt,
-            finishedAt: new Date().toISOString(),
-            status: "finished",
-            exitCode: globalExitCode.actual ?? globalExitCode.original,
-        });
-        exit(globalExitCode.actual ?? globalExitCode.original);
-    }
-    finally {
-        await rerunContext?.cleanup();
-    }
-};