allure 3.11.0 → 3.12.0

package/README.md

@@ -74,7 +74,27 @@ For example:
 npx allure agent -- npm test
 ```
 
-`allure agent` runs with an agent-only profile by default. It creates a fresh output directory automatically, accepts compact inline expectations such as `--goal`, `--expect-tests`, `--expect-test`, `--expect-label`, and `--expect-step-containing`, and can still load an expectations file with `--expectations` when needed. Configured presentation or export plugins such as Awesome or TestOps are ignored for that run.
+To analyze existing Allure results or dump archives downloaded from CI without
+rerunning tests, use `agent inspect`:
+
+```bash
+npx allure agent inspect path/to/allure-results
+npx allure agent inspect --dump allure-results-linux.zip --dump allure-results-macos.zip
+npx allure agent inspect --config ./allurerc.mjs --output ./agent-output path/to/allure-results
+```
+
+`agent inspect` accepts the same result inputs and configuration-style options as
+`allure generate`, including result directory globs, `--dump`, `--config`,
+`--cwd`, `--report-name`, `--history-limit`, and `--hide-labels`. Its `--output`
+option writes the agentic output directory.
+
+`allure agent` and `allure agent inspect` use `--report auto` by default. This writes the agent-readable artifacts and, when the stored visible result count is 1000 or fewer, also writes a single-file Awesome report at `awesome/index.html` inside the agent output directory. Runs above that threshold skip the human report to avoid excessive output, and the status is recorded in `index.md`, `manifest/run.json`, and `manifest/human-report.json`.
+
+Use `--report off` for agent-only artifacts, `--report awesome` to force the single-file Awesome report regardless of result count, or `--report config` to force the configured non-agent report plugins inside the agent output directory. Configured presentation or export plugins such as Dashboard or TestOps are otherwise ignored for agent runs.
+
+If you need the human-readable report from the most recent agent run, first run `npx allure agent latest` when the output directory is unknown. Then check `<output>/manifest/human-report.json`; when its status is `generated`, open `<output>/<path>` from that manifest, usually `<output>/awesome/index.html`.
+
+`allure agent` creates a fresh output directory automatically, accepts compact inline expectations such as `--goal`, `--expect-tests`, `--expect-test`, `--expect-label`, and `--expect-step-containing`, and can still load an expectations file with `--expectations` when needed.
 
 Agents and setup tools can inspect the local structured capability contract without scraping help text:
 

package/dist/commands/agent-human-report.d.ts

@@ -0,0 +1,23 @@
+import { type FullConfig, type PluginInstance } from "@allurereport/core";
+import type { AgentHumanReportMode, AgentHumanReportStatus, AgentHumanReportStatusProvider } from "@allurereport/plugin-agent";
+export declare const AGENT_HUMAN_REPORT_THRESHOLD = 1000;
+type AgentHumanReportConfigOverride = {
+    name?: FullConfig["name"];
+    open?: FullConfig["open"];
+    port?: FullConfig["port"];
+    hideLabels?: FullConfig["hideLabels"];
+    historyLimit?: FullConfig["historyLimit"];
+};
+type AgentHumanReportBuildParams = {
+    mode: AgentHumanReportMode;
+    cwd: string;
+    configPath?: string;
+    outputDir: string;
+    configOverride?: AgentHumanReportConfigOverride;
+};
+export declare const createAgentHumanReportConfig: ({ mode, cwd, configPath, outputDir, configOverride, }: AgentHumanReportBuildParams) => Promise<{
+    status: AgentHumanReportStatus;
+    statusProvider: AgentHumanReportStatusProvider;
+    plugins: PluginInstance[];
+}>;
+export {};

package/dist/commands/agent-human-report.js

@@ -0,0 +1,171 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _AgentHumanReportPlugin_realtime, _AgentHumanReportPlugin_generated;
+import * as console from "node:console";
+import { readConfig, readRawConfig } from "@allurereport/core";
+import AwesomePlugin from "@allurereport/plugin-awesome";
+export const AGENT_HUMAN_REPORT_THRESHOLD = 1000;
+const createInitialHumanReportStatus = (mode) => ({
+    schema_version: "allure-agent-human-report/v1",
+    mode,
+    status: mode === "off" ? "disabled" : "pending",
+    result_count: null,
+    threshold: AGENT_HUMAN_REPORT_THRESHOLD,
+    path: null,
+    reports: [],
+    reason: mode === "off" ? "disabled by --report off" : null,
+    error: null,
+});
+const isAgentPluginId = (id) => id === "agent" || id === "plugin-agent";
+const isAwesomeDescriptor = (id, descriptor) => id === "awesome" ||
+    id === "@allurereport/plugin-awesome" ||
+    descriptor.import === "awesome" ||
+    descriptor.import === "@allurereport/plugin-awesome";
+const configuredAwesomeOptions = async (cwd, configPath) => {
+    const rawConfig = await readRawConfig(cwd, configPath);
+    const plugins = rawConfig.plugins ?? {};
+    for (const id of Object.keys(plugins)) {
+        const descriptor = plugins[id];
+        if (isAwesomeDescriptor(id, descriptor)) {
+            return (descriptor.options ?? {});
+        }
+    }
+    return {};
+};
+const recordGeneratedReport = (status, pluginId, path) => {
+    const alreadyRecorded = status.reports.some((report) => report.plugin_id === pluginId && report.path === path);
+    if (!alreadyRecorded) {
+        status.reports.push({
+            plugin_id: pluginId,
+            path,
+        });
+    }
+    status.status = status.error ? "failed" : "generated";
+    status.path ?? (status.path = path);
+    status.reason = null;
+    status.generated_at = new Date().toISOString();
+};
+const recordFailedReport = (status, pluginId, error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    status.status = "failed";
+    status.error ?? (status.error = message);
+    status.errors = [...(status.errors ?? []), { plugin_id: pluginId, message }];
+};
+class AgentHumanReportPlugin {
+    constructor(params) {
+        this.params = params;
+        _AgentHumanReportPlugin_realtime.set(this, void 0);
+        _AgentHumanReportPlugin_generated.set(this, false);
+        this.start = async (_context, _store, realtime) => {
+            __classPrivateFieldSet(this, _AgentHumanReportPlugin_realtime, realtime, "f");
+        };
+        this.done = async (context, store) => {
+            const { mode, status, threshold, pluginId, plugin, reportPath } = this.params;
+            const resultCount = (await store.allTestResults()).length;
+            status.result_count = resultCount;
+            if (status.status === "skipped") {
+                return;
+            }
+            if (mode === "auto" && resultCount > threshold) {
+                status.status = "skipped";
+                status.reason = `result count ${resultCount} exceeds threshold ${threshold}`;
+                return;
+            }
+            try {
+                await plugin.start?.(context, store, __classPrivateFieldGet(this, _AgentHumanReportPlugin_realtime, "f"));
+                await plugin.done?.(context, store);
+                __classPrivateFieldSet(this, _AgentHumanReportPlugin_generated, true, "f");
+                recordGeneratedReport(status, pluginId, reportPath);
+            }
+            catch (error) {
+                recordFailedReport(status, pluginId, error);
+                console.error(`agent human report ${pluginId} error`, error);
+            }
+        };
+        this.info = async (context, store) => {
+            if (!__classPrivateFieldGet(this, _AgentHumanReportPlugin_generated, "f")) {
+                return undefined;
+            }
+            return this.params.plugin.info?.(context, store);
+        };
+    }
+}
+_AgentHumanReportPlugin_realtime = new WeakMap(), _AgentHumanReportPlugin_generated = new WeakMap();
+const wrapHumanReportPlugin = (params) => {
+    const { mode, status, plugin, reportPath = `${plugin.id}/` } = params;
+    return {
+        ...plugin,
+        plugin: new AgentHumanReportPlugin({
+            mode,
+            status,
+            threshold: AGENT_HUMAN_REPORT_THRESHOLD,
+            pluginId: plugin.id,
+            plugin: plugin.plugin,
+            reportPath,
+        }),
+    };
+};
+export const createAgentHumanReportConfig = async ({ mode, cwd, configPath, outputDir, configOverride, }) => {
+    const status = createInitialHumanReportStatus(mode);
+    const statusProvider = () => status;
+    if (mode === "off") {
+        return {
+            status,
+            statusProvider,
+            plugins: [],
+        };
+    }
+    if (mode === "auto" || mode === "awesome") {
+        const awesomeOptions = {
+            ...(await configuredAwesomeOptions(cwd, configPath)),
+            singleFile: true,
+        };
+        const awesomePlugin = {
+            id: "awesome",
+            enabled: true,
+            options: awesomeOptions,
+            plugin: new AwesomePlugin(awesomeOptions),
+        };
+        return {
+            status,
+            statusProvider,
+            plugins: [
+                wrapHumanReportPlugin({
+                    mode,
+                    status,
+                    plugin: awesomePlugin,
+                    reportPath: "awesome/index.html",
+                }),
+            ],
+        };
+    }
+    const reportConfig = await readConfig(cwd, configPath, {
+        ...configOverride,
+        output: outputDir,
+    });
+    const plugins = reportConfig.plugins
+        ?.filter((plugin) => !isAgentPluginId(plugin.id))
+        .map((plugin) => wrapHumanReportPlugin({
+        mode,
+        status,
+        plugin,
+    })) ?? [];
+    if (!plugins.length) {
+        status.status = "disabled";
+        status.reason = "no configured non-agent report plugins";
+    }
+    return {
+        status,
+        statusProvider,
+        plugins,
+    };
+};

package/dist/commands/agent-run.d.ts

@@ -1,7 +1,16 @@
-import { writeLatestAgentState, type AgentExpectationsInput } from "@allurereport/plugin-agent";
+import { writeAgentRunState, type AgentExpectationsInput, type AgentHumanReportMode } from "@allurereport/plugin-agent";
 export declare const formatAgentCommand: (args: string[]) => string;
+export declare const formatAgentInspectCommand: (params: {
+    dumps?: string[];
+    resultsDir?: string[];
+}) => string;
 export declare const printAgentOutputLinks: (outputDir: string) => void;
-export declare const persistLatestAgentState: (value: Parameters<typeof writeLatestAgentState>[0]) => Promise<void>;
+export declare const persistAgentRunState: (value: Parameters<typeof writeAgentRunState>[0]) => Promise<void>;
+export declare const cleanupManagedAgentOutputs: (params: {
+    cwd: string;
+    runId: string;
+    managedOutput: boolean;
+}) => Promise<void>;
 export type ExecuteAgentModeParams = {
     configPath?: string;
     cwd?: string;
@@ -16,6 +25,25 @@ export type ExecuteAgentModeParams = {
     rerunPreset?: string;
     rerunEnvironments?: string[];
     rerunLabels?: string[];
+    reportMode: AgentHumanReportMode;
     args: string[];
 };
 export declare const executeAgentMode: (params: ExecuteAgentModeParams) => Promise<void>;
+export type ExecuteAgentInspectModeParams = {
+    configPath?: string;
+    cwd?: string;
+    output?: string;
+    expectations?: string;
+    inlineExpectations?: AgentExpectationsInput;
+    environment?: string;
+    environmentName?: string;
+    reportName?: string;
+    open?: boolean;
+    port?: string;
+    historyLimit?: string;
+    hideLabels?: string[];
+    dumps?: string[];
+    reportMode: AgentHumanReportMode;
+    resultsDir: string[];
+};
+export declare const executeAgentInspectMode: (params: ExecuteAgentInspectModeParams) => Promise<never>;

package/dist/commands/agent-run.js

@@ -1,29 +1,73 @@
 import * as console from "node:console";
+import { randomUUID } from "node:crypto";
 import { mkdtemp, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import process, { exit } from "node:process";
 import { AllureReport, isFileNotFoundError, readConfig } from "@allurereport/core";
-import { createAgentTestPlanContext, AgentUsageError, formatAgentOutputLinks, isPathInside, normalizeAgentRerunPreset, parseAgentLabelFilters, resolveAgentStateDir, writeLatestAgentState, } from "@allurereport/plugin-agent";
+import { createAgentTestPlanContext, AgentUsageError, formatAgentOutputLinks, isPathInside, normalizeAgentRerunPreset, parseAgentLabelFilters, cleanupAgentRunState, cleanupStaleAgentRunStates, resolveAgentStateDir, writeAgentRunState, } from "@allurereport/plugin-agent";
 import { normalizeCommandEnvironmentOptions, resolveCommandEnvironment } from "../utils/environment.js";
 import { createChildAllureCliEnvironment, getActiveAllureCliCommand } from "../utils/execution-context.js";
+import { findAllureResultDirectories, findFilesByGlobs } from "../utils/fileSystem.js";
+import { createAgentHumanReportConfig } from "./agent-human-report.js";
 import { executeAllureRun, executeNestedAllureCommand } from "./commons/run.js";
 export const formatAgentCommand = (args) => args.join(" ");
+export const formatAgentInspectCommand = (params) => [
+    "allure",
+    "agent",
+    "inspect",
+    ...(params.dumps ?? []).flatMap((dump) => ["--dump", dump]),
+    ...(params.resultsDir ?? []),
+].join(" ");
 export const printAgentOutputLinks = (outputDir) => {
     for (const line of formatAgentOutputLinks(outputDir)) {
         console.log(line);
     }
 };
-export const persistLatestAgentState = async (value) => {
+export const persistAgentRunState = async (value) => {
     try {
-        await writeLatestAgentState(value);
+        await writeAgentRunState(value);
     }
     catch (error) {
-        console.error(`Could not update latest agent output in ${resolveAgentStateDir(value.cwd)}: ${error.message}`);
+        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 logAgentOrphanCleanupFailures = (failures) => {
+    for (const failure of failures) {
+        console.error(`Could not clean stale agent output ${failure.outputDir}: ${failure.error.message}`);
+    }
+};
+export const cleanupManagedAgentOutputs = async (params) => {
+    try {
+        const result = await cleanupAgentRunState({
+            cwd: params.cwd,
+            currentRunId: params.runId,
+            keepManagedRuns: params.managedOutput ? 1 : 0,
+        });
+        logAgentCleanupFailures(result.failed);
+    }
+    catch (error) {
+        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}`);
     }
 };
 export const executeAgentMode = async (params) => {
-    const { configPath, cwd: configuredCwd, output, expectations, inlineExpectations, environment, environmentName, silent, rerunFrom, rerunLatest, rerunPreset, rerunEnvironments, rerunLabels, args, } = params;
+    const { configPath, cwd: configuredCwd, output, expectations, inlineExpectations, environment, environmentName, silent, rerunFrom, rerunLatest, rerunPreset, rerunEnvironments, rerunLabels, reportMode, args, } = params;
     const command = args[0];
     const commandArgs = args.slice(1);
     const cwd = await realpath(configuredCwd ?? process.cwd());
@@ -58,6 +102,8 @@ export const executeAgentMode = async (params) => {
             exit(exitCode ?? -1);
             return;
         }
+        const runId = randomUUID();
+        const managedOutput = !output;
         const outputDir = output ? resolve(cwd, output) : await mkdtemp(join(tmpdir(), "allure-agent-"));
         const expectationsPath = expectations ? resolve(cwd, expectations) : undefined;
         const environmentOptions = {
@@ -68,6 +114,12 @@ export const executeAgentMode = async (params) => {
         if (expectationsPath && isPathInside(outputDir, expectationsPath)) {
             throw new AgentUsageError(`--expectations path ${JSON.stringify(expectationsPath)} must not be inside the agent output directory ${JSON.stringify(outputDir)}`);
         }
+        const humanReport = await createAgentHumanReportConfig({
+            mode: reportMode,
+            cwd,
+            configPath,
+            outputDir,
+        });
         const config = await readConfig(cwd, configPath, {
             output: outputDir,
             plugins: {
@@ -75,6 +127,7 @@ export const executeAgentMode = async (params) => {
                     options: {
                         outputDir,
                         command: commandString,
+                        humanReport: humanReport.statusProvider,
                         ...(expectationsPath ? { expectationsPath } : {}),
                         ...(inlineExpectations ? { expectations: inlineExpectations } : {}),
                     },
@@ -90,14 +143,17 @@ export const executeAgentMode = async (params) => {
                 console.error("could not clean output directory", error);
             }
         }
-        const startedAt = new Date().toISOString();
-        await persistLatestAgentState({
+        const startedAt = Date.now();
+        await persistAgentRunState({
+            runId,
             cwd,
             outputDir,
+            managedOutput,
             expectationsPath,
             command: commandString,
             startedAt,
             status: "running",
+            pid: process.pid,
         });
         printAgentOutputLinks(outputDir);
         if (expectationsPath) {
@@ -116,7 +172,7 @@ export const executeAgentMode = async (params) => {
             qualityGate: undefined,
             allureService: undefined,
             realTime: false,
-            plugins: config.plugins,
+            plugins: [...humanReport.plugins, ...(config.plugins ?? [])],
         });
         const knownIssues = await allureReport.store.allKnownIssues();
         const { globalExitCode } = await executeAllureRun({
@@ -133,19 +189,147 @@ export const executeAgentMode = async (params) => {
             ignoreLogs: false,
             logProcessExit: false,
         });
-        await persistLatestAgentState({
+        await persistAgentRunState({
+            runId,
             cwd,
             outputDir,
+            managedOutput,
             expectationsPath,
             command: commandString,
             startedAt,
-            finishedAt: new Date().toISOString(),
+            finishedAt: Date.now(),
             status: "finished",
             exitCode: globalExitCode.actual ?? globalExitCode.original,
+            pid: process.pid,
         });
+        await cleanupManagedAgentOutputs({ cwd, runId, managedOutput });
         exit(globalExitCode.actual ?? globalExitCode.original);
     }
     finally {
         await rerunContext?.cleanup();
     }
 };
+export const executeAgentInspectMode = async (params) => {
+    const { configPath, cwd: configuredCwd, output, expectations, inlineExpectations, environment, environmentName, reportName, open, port, historyLimit, hideLabels, dumps = [], reportMode, resultsDir, } = params;
+    const cwd = await realpath(configuredCwd ?? process.cwd());
+    const dumpFiles = dumps.length ? await findFilesByGlobs(cwd, dumps) : [];
+    const shouldReadResults = resultsDir.length > 0 || dumps.length === 0;
+    const { resultDirectories = [], patterns = resultsDir } = shouldReadResults
+        ? await findAllureResultDirectories(cwd, resultsDir)
+        : {};
+    if (dumps.length > 0 && dumpFiles.length === 0) {
+        throw new AgentUsageError(`No dump files found matching pattern: ${dumps.join(", ")}`);
+    }
+    if (resultDirectories.length === 0 && dumpFiles.length === 0) {
+        const inspectedPatterns = [...(patterns ?? []), ...dumps];
+        throw new AgentUsageError(`No test results directories or dump files found matching pattern: ${inspectedPatterns}`);
+    }
+    const runId = randomUUID();
+    const managedOutput = !output;
+    const outputDir = output ? resolve(cwd, output) : await mkdtemp(join(tmpdir(), "allure-agent-"));
+    const expectationsPath = expectations ? resolve(cwd, expectations) : undefined;
+    const commandString = formatAgentInspectCommand({ dumps: dumpFiles, resultsDir: resultDirectories });
+    const hiddenLabels = hideLabels?.length ? hideLabels : undefined;
+    const environmentOptions = {
+        environment,
+        environmentName,
+    };
+    normalizeCommandEnvironmentOptions(environmentOptions);
+    if (expectationsPath && isPathInside(outputDir, expectationsPath)) {
+        throw new AgentUsageError(`--expectations path ${JSON.stringify(expectationsPath)} must not be inside the agent output directory ${JSON.stringify(outputDir)}`);
+    }
+    const historyLimitValue = historyLimit ? parseInt(historyLimit, 10) : undefined;
+    const humanReport = await createAgentHumanReportConfig({
+        mode: reportMode,
+        cwd,
+        configPath,
+        outputDir,
+        configOverride: {
+            name: reportName,
+            open,
+            port,
+            hideLabels: hiddenLabels,
+            historyLimit: historyLimitValue,
+        },
+    });
+    const config = await readConfig(cwd, configPath, {
+        name: reportName,
+        output: outputDir,
+        open,
+        port,
+        hideLabels: hiddenLabels,
+        historyLimit: historyLimitValue,
+        plugins: {
+            agent: {
+                options: {
+                    outputDir,
+                    command: commandString,
+                    humanReport: humanReport.statusProvider,
+                    ...(expectationsPath ? { expectationsPath } : {}),
+                    ...(inlineExpectations ? { expectations: inlineExpectations } : {}),
+                },
+            },
+        },
+    });
+    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 = Date.now();
+    await persistAgentRunState({
+        runId,
+        cwd,
+        outputDir,
+        managedOutput,
+        expectationsPath,
+        command: commandString,
+        startedAt,
+        status: "running",
+        pid: process.pid,
+    });
+    printAgentOutputLinks(outputDir);
+    if (expectationsPath) {
+        console.log(`agent expectations: ${expectationsPath}`);
+    }
+    else if (inlineExpectations) {
+        console.log("agent expectations: CLI options");
+    }
+    console.log(commandString);
+    const allureReport = new AllureReport({
+        ...config,
+        output: outputDir,
+        environment: resolvedEnvironment?.id,
+        open: false,
+        port: undefined,
+        qualityGate: undefined,
+        allureService: undefined,
+        realTime: false,
+        plugins: [...humanReport.plugins, ...(config.plugins ?? [])],
+    });
+    await allureReport.restoreState(Array.from(dumpFiles));
+    await allureReport.start();
+    for (const dir of resultDirectories) {
+        await allureReport.readDirectory(dir);
+    }
+    await allureReport.done();
+    await persistAgentRunState({
+        runId,
+        cwd,
+        outputDir,
+        managedOutput,
+        expectationsPath,
+        command: commandString,
+        startedAt,
+        finishedAt: Date.now(),
+        status: "finished",
+        exitCode: 0,
+        pid: process.pid,
+    });
+    await cleanupManagedAgentOutputs({ cwd, runId, managedOutput });
+    exit(0);
+};

package/dist/commands/agent.d.ts

@@ -13,6 +13,7 @@ export declare class AgentCommand extends Command {
     config: string | undefined;
     cwd: string | undefined;
     output: string | undefined;
+    report: string | undefined;
     expectations: string | undefined;
     goal: string[] | undefined;
     taskId: string[] | undefined;
@@ -37,6 +38,37 @@ export declare class AgentCommand extends Command {
     commandToRun: string[];
     execute(): Promise<void>;
 }
+export declare class AgentInspectCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    resultsDir: string[];
+    config: string | undefined;
+    cwd: string | undefined;
+    output: string | undefined;
+    report: string | undefined;
+    reportName: string | undefined;
+    dump: string[] | undefined;
+    open: boolean | undefined;
+    port: string | undefined;
+    historyLimit: string | undefined;
+    hideLabels: string[] | undefined;
+    expectations: string | undefined;
+    goal: string[] | undefined;
+    taskId: string[] | undefined;
+    expectTests: string[] | undefined;
+    expectLabels: string[] | undefined;
+    expectEnvironments: string[] | undefined;
+    expectFullNames: string[] | undefined;
+    expectPrefixes: string[] | undefined;
+    forbidLabels: string[] | undefined;
+    expectStepContains: string[] | undefined;
+    expectSteps: string[] | undefined;
+    expectAttachments: string[] | undefined;
+    expectAttachmentFilters: string[] | undefined;
+    environment: string | undefined;
+    environmentName: string | undefined;
+    execute(): Promise<void>;
+}
 export declare class AgentLatestCommand extends Command {
     static paths: string[][];
     static usage: import("clipanion").Usage;

package/dist/commands/agent.js

@@ -1,26 +1,83 @@
 import * as console from "node:console";
+import { randomUUID } from "node:crypto";
 import { mkdir, mkdtemp, realpath, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import process, { exit } from "node:process";
-import { AGENT_FINDING_CATEGORIES, AGENT_FINDING_SEVERITIES, AGENT_TASK_MAP_HELP, AGENT_TEST_STATUSES, AgentExpectationUsageError, buildAgentInlineExpectations, buildAgentQueryPayload, createAgentCapabilities, formatAgentOutputLinks, isAgentExpectationUsageError, isAgentTaskMapHelpRequest, isAgentUsageError, loadAgentOutput, normalizeAgentQueryLimit, normalizeAgentQueryView, normalizeAgentRerunPreset, normalizeRepeatedEnumValues, normalizeRepeatedStringValues, parseAgentLabelFilters, readLatestAgentState, resolveAgentSelectionOutputDir, resolveAgentStateDir, selectAgentTestPlan, validateAgentExpectationsFile, writeLatestAgentState, writeInvalidAgentExpectationOutput, } from "@allurereport/plugin-agent";
+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";
 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 persistLatestAgentState = async (value) => {
+const persistAgentRunState = async (value) => {
+    try {
+        await writeAgentRunState(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 logAgentOrphanCleanupFailures = (failures) => {
+    for (const failure of failures) {
+        console.error(`Could not clean stale agent output ${failure.outputDir}: ${failure.error.message}`);
+    }
+};
+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 agentEnvironmentOption = () => Option.String("--environment,--env", {
@@ -35,6 +92,15 @@ const throwCliUsageError = (error) => {
     }
     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);
@@ -65,7 +131,10 @@ 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",
@@ -133,24 +202,25 @@ export class AgentCommand extends Command {
         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 || !args.length) {
+        if (!args.length) {
             throw new UsageError("expecting command to be specified after --, e.g. allure agent -- npm run test");
         }
         try {
-            const inlineExpectations = buildAgentInlineExpectations({
+            const inlineExpectations = buildInlineExpectationsFromOptions({
                 goal: this.goal,
                 taskId: this.taskId,
                 expectTests: this.expectTests,
-                expectLabels: readOptionalStringArray(this.expectLabels),
-                expectEnvironments: readOptionalStringArray(this.expectEnvironments),
-                expectFullNames: readOptionalStringArray(this.expectFullNames),
-                expectPrefixes: readOptionalStringArray(this.expectPrefixes),
-                forbidLabels: readOptionalStringArray(this.forbidLabels),
-                expectStepContains: readOptionalStringArray(this.expectStepContains),
+                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: readOptionalStringArray(this.expectAttachmentFilters),
+                expectAttachmentFilters: this.expectAttachmentFilters,
             });
             if (expectations && inlineExpectations) {
                 throw new AgentExpectationUsageError("Use either --expectations <file> or inline expectation flags, not both", "--expectations");
@@ -175,6 +245,7 @@ export class AgentCommand extends Command {
                 rerunPreset: readOptionalString(this.rerunPreset),
                 rerunEnvironments: readOptionalStringArray(this.rerunEnvironments),
                 rerunLabels: readOptionalStringArray(this.rerunLabels),
+                reportMode,
                 args,
             });
         }
@@ -184,6 +255,8 @@ export class AgentCommand extends Command {
             }
             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({
@@ -191,15 +264,21 @@ export class AgentCommand extends Command {
                 command: commandString,
                 error: expectationError,
             });
-            await persistLatestAgentState({
+            const generatedAtMs = Date.parse(generatedAt);
+            const generatedAtTimestamp = Number.isFinite(generatedAtMs) ? generatedAtMs : Date.now();
+            await persistAgentRunState({
+                runId,
                 cwd,
                 outputDir,
+                managedOutput,
                 command: commandString,
-                startedAt: generatedAt,
-                finishedAt: generatedAt,
+                startedAt: generatedAtTimestamp,
+                finishedAt: generatedAtTimestamp,
                 status: "finished",
                 exitCode: 1,
+                pid: process.pid,
             });
+            await cleanupManagedAgentOutputs({ cwd, runId, managedOutput });
             printAgentOutputLinks(outputDir);
             console.error(expectationError.message);
             exit(1);
@@ -209,15 +288,206 @@ export class AgentCommand extends Command {
 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);
@@ -247,7 +517,7 @@ export class AgentLatestCommand extends Command {
 AgentLatestCommand.paths = [["agent", "latest"]];
 AgentLatestCommand.usage = Command.Usage({
     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.",
+    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 and index path for the current project"],
         [
@@ -270,11 +540,11 @@ 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 {

package/dist/index.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import process, { argv } from "node:process";
 import { Builtins, Cli } from "clipanion";
-import { AgentCommand, AGENT_TASK_MAP_HELP, AgentCapabilitiesCommand, AgentLatestCommand, AgentQueryCommand, AgentSelectCommand, AgentStateDirCommand, Allure2Command, AwesomeCommand, CheckCommand, ClassicCommand, CsvCommand, DashboardCommand, GenerateCommand, HistoryCommand, JiraClearCommand, KnownIssueCommand, LogCommand, OpenCommand, QualityGateCommand, ResultsPackCommand, ResultsUnpackCommand, RunCommand, SlackCommand, TestPlanCommand, WatchCommand, isAgentTaskMapHelpRequest, } from "./commands/index.js";
+import { AgentCommand, AGENT_TASK_MAP_HELP, AgentCapabilitiesCommand, AgentInspectCommand, AgentLatestCommand, AgentQueryCommand, AgentSelectCommand, AgentStateDirCommand, Allure2Command, AwesomeCommand, CheckCommand, ClassicCommand, CsvCommand, DashboardCommand, GenerateCommand, HistoryCommand, JiraClearCommand, KnownIssueCommand, LogCommand, OpenCommand, QualityGateCommand, ResultsPackCommand, ResultsUnpackCommand, RunCommand, SlackCommand, TestPlanCommand, WatchCommand, isAgentTaskMapHelpRequest, } from "./commands/index.js";
 const [node, app, ...args] = argv;
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const cli = new Cli({
@@ -12,6 +12,7 @@ const cli = new Cli({
 cli.register(AwesomeCommand);
 cli.register(Allure2Command);
 cli.register(AgentCapabilitiesCommand);
+cli.register(AgentInspectCommand);
 cli.register(AgentLatestCommand);
 cli.register(AgentQueryCommand);
 cli.register(AgentSelectCommand);

package/dist/utils/process.js

@@ -4,6 +4,50 @@ import { platform } from "process";
 import { invokeStdoutCliTool } from "@allurereport/reader-api";
 const IS_WIN = platform === "win32";
 const PS_OUTPUT_PATTERN = /(?<ppid>\d+)\s+(?<pid>\d+)\s+(?<comm>.*)/;
+const quotePosixShellArg = (arg) => {
+    if (/^[A-Za-z0-9_/:=.,@%+-]+$/u.test(arg)) {
+        return arg;
+    }
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+};
+const quoteWindowsShellArg = (arg) => {
+    if (arg && !/[\s"&()<>^|%]/u.test(arg)) {
+        return arg;
+    }
+    let quoted = '"';
+    let backslashes = 0;
+    for (const char of arg) {
+        if (char === "\\") {
+            backslashes += 1;
+            continue;
+        }
+        if (char === '"') {
+            quoted += "\\".repeat(backslashes * 2 + 1);
+            quoted += char;
+            backslashes = 0;
+            continue;
+        }
+        quoted += "\\".repeat(backslashes);
+        backslashes = 0;
+        quoted += char;
+    }
+    quoted += "\\".repeat(backslashes * 2);
+    quoted += '"';
+    return quoted;
+};
+const quoteShellArg = IS_WIN ? quoteWindowsShellArg : quotePosixShellArg;
+const resolveShellInvocation = (command, commandArgs, shell) => {
+    if (!shell || commandArgs.length === 0) {
+        return {
+            command,
+            commandArgs,
+        };
+    }
+    return {
+        command: [command, ...commandArgs].map(quoteShellArg).join(" "),
+        commandArgs: [],
+    };
+};
 export const runProcess = (params) => {
     const { command, commandArgs, cwd, environmentVariables = {}, logs = "inherit", shell = IS_WIN } = params;
     const env = {
@@ -20,7 +64,8 @@ export const runProcess = (params) => {
         });
         delete env.NO_COLOR;
     }
-    return spawn(command, commandArgs, {
+    const processInvocation = resolveShellInvocation(command, commandArgs, shell);
+    return spawn(processInvocation.command, processInvocation.commandArgs, {
         env,
         cwd,
         stdio: logs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allure",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Allure Commandline Tool",
   "keywords": [
     "allure",
@@ -32,26 +32,26 @@
     "lint:fix": "oxlint --import-plugin --fix src test features stories"
   },
   "dependencies": {
-    "@allurereport/charts-api": "3.11.0",
-    "@allurereport/ci": "3.11.0",
-    "@allurereport/core": "3.11.0",
-    "@allurereport/core-api": "3.11.0",
-    "@allurereport/directory-watcher": "3.11.0",
-    "@allurereport/plugin-agent": "3.11.0",
-    "@allurereport/plugin-allure2": "3.11.0",
-    "@allurereport/plugin-api": "3.11.0",
-    "@allurereport/plugin-awesome": "3.11.0",
-    "@allurereport/plugin-classic": "3.11.0",
-    "@allurereport/plugin-csv": "3.11.0",
-    "@allurereport/plugin-dashboard": "3.11.0",
-    "@allurereport/plugin-jira": "3.11.0",
-    "@allurereport/plugin-log": "3.11.0",
-    "@allurereport/plugin-progress": "3.11.0",
-    "@allurereport/plugin-server-reload": "3.11.0",
-    "@allurereport/plugin-slack": "3.11.0",
-    "@allurereport/reader-api": "3.11.0",
-    "@allurereport/service": "3.11.0",
-    "@allurereport/static-server": "3.11.0",
+    "@allurereport/charts-api": "3.12.0",
+    "@allurereport/ci": "3.12.0",
+    "@allurereport/core": "3.12.0",
+    "@allurereport/core-api": "3.12.0",
+    "@allurereport/directory-watcher": "3.12.0",
+    "@allurereport/plugin-agent": "3.12.0",
+    "@allurereport/plugin-allure2": "3.12.0",
+    "@allurereport/plugin-api": "3.12.0",
+    "@allurereport/plugin-awesome": "3.12.0",
+    "@allurereport/plugin-classic": "3.12.0",
+    "@allurereport/plugin-csv": "3.12.0",
+    "@allurereport/plugin-dashboard": "3.12.0",
+    "@allurereport/plugin-jira": "3.12.0",
+    "@allurereport/plugin-log": "3.12.0",
+    "@allurereport/plugin-progress": "3.12.0",
+    "@allurereport/plugin-server-reload": "3.12.0",
+    "@allurereport/plugin-slack": "3.12.0",
+    "@allurereport/reader-api": "3.12.0",
+    "@allurereport/service": "3.12.0",
+    "@allurereport/static-server": "3.12.0",
     "adm-zip": "^0.5.16",
     "clipanion": "^4.0.0-rc.4",
     "glob": "^13.0.6",