@allurereport/plugin-agent 3.10.0 → 3.12.0

package/dist/state.js

@@ -0,0 +1,277 @@
+import { appendFile, readFile, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { isFileNotFoundError, listAgentManagedTempOutputDirs, listAgentStatePaths, pathExists, projectStatePath, readPathMtimeMs, tryWithAgentStateLock, withAgentStateLock, writeJsonlAtomic, } from "./utils.js";
+export { ALLURE_AGENT_STATE_DIR_ENV, resolveAgentStateDir } from "./utils.js";
+const AGENT_RUN_STATE_SCHEMA = "allure-agent-run/v1";
+const AGENT_STALE_OUTPUT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const isAgentRunState = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.schema === AGENT_RUN_STATE_SCHEMA &&
+        typeof candidate.runId === "string" &&
+        typeof candidate.cwd === "string" &&
+        typeof candidate.outputDir === "string" &&
+        typeof candidate.managedOutput === "boolean" &&
+        typeof candidate.command === "string" &&
+        typeof candidate.startedAt === "number" &&
+        Number.isSafeInteger(candidate.startedAt) &&
+        (candidate.expectationsPath === undefined || typeof candidate.expectationsPath === "string") &&
+        (candidate.finishedAt === undefined ||
+            (typeof candidate.finishedAt === "number" && Number.isSafeInteger(candidate.finishedAt))) &&
+        (candidate.status === "running" || candidate.status === "finished") &&
+        (candidate.exitCode === undefined || typeof candidate.exitCode === "number" || candidate.exitCode === null) &&
+        (candidate.pid === undefined || (typeof candidate.pid === "number" && Number.isSafeInteger(candidate.pid))));
+};
+const normalizeAgentRunState = (value) => ({
+    schema: AGENT_RUN_STATE_SCHEMA,
+    runId: value.runId,
+    cwd: resolve(value.cwd),
+    outputDir: resolve(value.outputDir),
+    managedOutput: value.managedOutput,
+    expectationsPath: value.expectationsPath ? resolve(value.expectationsPath) : undefined,
+    command: value.command,
+    startedAt: value.startedAt,
+    finishedAt: value.finishedAt,
+    status: value.status,
+    exitCode: value.exitCode,
+    pid: value.pid,
+});
+const readAgentRunStateFile = async (statePath, cwd) => {
+    const normalizedCwd = cwd === undefined ? undefined : resolve(cwd);
+    let raw;
+    try {
+        raw = await readFile(statePath, "utf-8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return [];
+        }
+        throw error;
+    }
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (!isAgentRunState(parsed)) {
+                return [];
+            }
+            return normalizedCwd === undefined || parsed.cwd === normalizedCwd ? [parsed] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+};
+const readAgentRunStateLines = async (cwd) => {
+    const normalizedCwd = resolve(cwd);
+    return readAgentRunStateFile(projectStatePath(normalizedCwd), normalizedCwd);
+};
+const foldAgentRunStates = (states) => {
+    const order = [];
+    const latestByRunId = new Map();
+    for (const state of states) {
+        if (!latestByRunId.has(state.runId)) {
+            order.push(state.runId);
+        }
+        latestByRunId.set(state.runId, state);
+    }
+    return order
+        .map((runId) => latestByRunId.get(runId))
+        .filter((state) => state !== undefined)
+        .sort((a, b) => a.startedAt - b.startedAt || (a.finishedAt ?? a.startedAt) - (b.finishedAt ?? b.startedAt));
+};
+const getAgentRunStateAgeTimestamp = (state) => state.finishedAt ?? state.startedAt;
+const isManagedOutputStale = (state, now, staleOutputTtlMs) => state.managedOutput && now - getAgentRunStateAgeTimestamp(state) >= staleOutputTtlMs;
+const isAgentOutputDirectory = async (outputDir) => (await pathExists(join(outputDir, "manifest", "run.json"))) || (await pathExists(join(outputDir, "index.md")));
+const cleanupStaleAgentRunState = async (params) => {
+    const states = foldAgentRunStates(await readAgentRunStateLines(params.cwd));
+    const retained = [];
+    const deleted = [];
+    const failed = [];
+    for (const state of states) {
+        if (!(await pathExists(state.outputDir))) {
+            continue;
+        }
+        if (!isManagedOutputStale(state, params.now, params.staleOutputTtlMs)) {
+            retained.push(state);
+            continue;
+        }
+        try {
+            await rm(state.outputDir, { recursive: true, force: true });
+            deleted.push(state);
+        }
+        catch (error) {
+            retained.push(state);
+            failed.push({ state, error });
+        }
+    }
+    await writeJsonlAtomic(projectStatePath(params.cwd), retained);
+    return {
+        deleted,
+        failed,
+        retained,
+    };
+};
+const cleanupStaleOrphanAgentOutputs = async (params) => {
+    const outputDirs = await listAgentManagedTempOutputDirs();
+    const deleted = [];
+    const failed = [];
+    const retained = [];
+    for (const outputDir of outputDirs) {
+        const normalizedOutputDir = resolve(outputDir);
+        if (params.referencedOutputDirs.has(normalizedOutputDir)) {
+            retained.push(normalizedOutputDir);
+            continue;
+        }
+        let mtimeMs;
+        try {
+            mtimeMs = await readPathMtimeMs(normalizedOutputDir);
+        }
+        catch (error) {
+            if (!isFileNotFoundError(error)) {
+                failed.push({ outputDir: normalizedOutputDir, error });
+            }
+            continue;
+        }
+        if (params.now - mtimeMs < params.staleOutputTtlMs) {
+            retained.push(normalizedOutputDir);
+            continue;
+        }
+        if (!(await isAgentOutputDirectory(normalizedOutputDir))) {
+            retained.push(normalizedOutputDir);
+            continue;
+        }
+        try {
+            await rm(normalizedOutputDir, { recursive: true, force: true });
+            deleted.push(normalizedOutputDir);
+        }
+        catch (error) {
+            failed.push({ outputDir: normalizedOutputDir, error });
+        }
+    }
+    return {
+        deleted,
+        failed,
+        retained,
+    };
+};
+export const writeAgentRunState = async (value) => {
+    const normalizedState = normalizeAgentRunState(value);
+    await withAgentStateLock(normalizedState.cwd, async () => {
+        await appendFile(projectStatePath(normalizedState.cwd), `${JSON.stringify(normalizedState)}\n`, "utf-8");
+    });
+    return normalizedState;
+};
+export const writeLatestAgentState = writeAgentRunState;
+export const readAgentRunStates = async (cwd) => foldAgentRunStates(await readAgentRunStateLines(cwd));
+export const readLatestAgentState = async (cwd) => {
+    const states = await readAgentRunStates(cwd);
+    for (let i = states.length - 1; i >= 0; i -= 1) {
+        const state = states[i];
+        if (await pathExists(state.outputDir)) {
+            return state;
+        }
+    }
+    return undefined;
+};
+export const cleanupAgentRunState = async (params) => withAgentStateLock(params.cwd, async () => {
+    const keepManagedRuns = Math.max(0, params.keepManagedRuns ?? 1);
+    const states = foldAgentRunStates(await readAgentRunStateLines(params.cwd));
+    const existing = [];
+    for (const state of states) {
+        if (await pathExists(state.outputDir)) {
+            existing.push(state);
+        }
+    }
+    const retainedManagedRunIds = new Set(existing
+        .filter((state) => state.managedOutput && state.status === "finished")
+        .sort((a, b) => (b.finishedAt ?? b.startedAt) - (a.finishedAt ?? a.startedAt) || b.startedAt - a.startedAt)
+        .slice(0, keepManagedRuns)
+        .map((state) => state.runId));
+    if (params.currentRunId) {
+        retainedManagedRunIds.add(params.currentRunId);
+    }
+    const deleted = [];
+    const failed = [];
+    for (const state of existing) {
+        if (!state.managedOutput || state.status !== "finished" || retainedManagedRunIds.has(state.runId)) {
+            continue;
+        }
+        try {
+            await rm(state.outputDir, { recursive: true, force: true });
+            deleted.push(state);
+        }
+        catch (error) {
+            failed.push({ state, error });
+        }
+    }
+    const deletedRunIds = new Set(deleted.map((state) => state.runId));
+    const retained = existing.filter((state) => !deletedRunIds.has(state.runId));
+    await writeJsonlAtomic(projectStatePath(params.cwd), retained);
+    return {
+        deleted,
+        failed,
+        retained,
+    };
+});
+export const cleanupStaleAgentRunStates = async (params) => {
+    const currentCwd = resolve(params.cwd);
+    const currentStatePath = projectStatePath(currentCwd);
+    const statePaths = await listAgentStatePaths(currentCwd);
+    const staleOutputTtlMs = Math.max(0, params.staleOutputTtlMs ?? AGENT_STALE_OUTPUT_TTL_MS);
+    const now = params.now ?? Date.now();
+    const staleCwds = new Map();
+    const referencedOutputDirs = new Set();
+    for (const statePath of statePaths) {
+        const states = foldAgentRunStates(await readAgentRunStateFile(statePath));
+        for (const state of states) {
+            referencedOutputDirs.add(resolve(state.outputDir));
+            if (statePath === currentStatePath) {
+                continue;
+            }
+            if (state.cwd === currentCwd || state.runId === params.currentRunId) {
+                continue;
+            }
+            if (!(await pathExists(state.outputDir)) || isManagedOutputStale(state, now, staleOutputTtlMs)) {
+                staleCwds.set(state.cwd, statePath);
+                break;
+            }
+        }
+    }
+    const deleted = [];
+    const failed = [];
+    const retained = [];
+    const skipped = [];
+    for (const [cwd, statePath] of staleCwds) {
+        const lockResult = await tryWithAgentStateLock(cwd, () => cleanupStaleAgentRunState({
+            cwd,
+            now,
+            staleOutputTtlMs,
+        }));
+        if (!lockResult.acquired) {
+            skipped.push({ cwd, statePath, reason: "locked" });
+            continue;
+        }
+        deleted.push(...lockResult.result.deleted);
+        failed.push(...lockResult.result.failed);
+        retained.push(...lockResult.result.retained);
+    }
+    const orphaned = await cleanupStaleOrphanAgentOutputs({
+        referencedOutputDirs,
+        now,
+        staleOutputTtlMs,
+    });
+    return {
+        checked: statePaths.length,
+        deleted,
+        failed,
+        orphaned,
+        retained,
+        skipped,
+    };
+};

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+export declare const ALLURE_AGENT_STATE_DIR_ENV = "ALLURE_AGENT_STATE_DIR";
+export declare const AGENT_MANAGED_OUTPUT_DIR_PREFIX = "allure-agent-";
+export declare const isFileNotFoundError: (error: unknown) => error is NodeJS.ErrnoException;
+export declare const resolveAgentStateDir: (_cwd?: string) => string;
+export declare const projectStatePath: (cwd: string) => string;
+export declare const listAgentStatePaths: (cwd?: string) => Promise<string[]>;
+export declare const listAgentManagedTempOutputDirs: () => Promise<string[]>;
+export declare const writeJsonlAtomic: (filePath: string, values: readonly unknown[]) => Promise<void>;
+export declare const withAgentStateLock: <T>(cwd: string, operation: () => Promise<T>) => Promise<T>;
+export declare const tryWithAgentStateLock: <T>(cwd: string, operation: () => Promise<T>) => Promise<{
+    acquired: true;
+    result: T;
+} | {
+    acquired: false;
+}>;
+export declare const pathExists: (path: string) => Promise<boolean>;
+export declare const readPathMtimeMs: (path: string) => Promise<number>;

package/dist/utils.js

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+export const ALLURE_AGENT_STATE_DIR_ENV = "ALLURE_AGENT_STATE_DIR";
+export const AGENT_MANAGED_OUTPUT_DIR_PREFIX = "allure-agent-";
+const AGENT_STATE_LOCK_STALE_MS = 10 * 60 * 1000;
+const AGENT_STATE_LOCK_RETRIES = 100;
+const AGENT_STATE_LOCK_RETRY_MS = 20;
+export const isFileNotFoundError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+const isFileExistsError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+const projectHash = (cwd) => createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+export const resolveAgentStateDir = (_cwd) => {
+    const configuredDir = process.env[ALLURE_AGENT_STATE_DIR_ENV]?.trim();
+    if (configuredDir) {
+        return resolve(configuredDir);
+    }
+    return join(tmpdir(), "allure-agent-state");
+};
+export const projectStatePath = (cwd) => join(resolveAgentStateDir(cwd), `${projectHash(resolve(cwd))}.jsonl`);
+const projectLockPath = (cwd) => join(resolveAgentStateDir(cwd), `${projectHash(resolve(cwd))}.lock`);
+export const listAgentStatePaths = async (cwd) => {
+    const stateDir = resolveAgentStateDir(cwd);
+    try {
+        const entries = await readdir(stateDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+            .map((entry) => join(stateDir, entry.name));
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return [];
+        }
+        throw error;
+    }
+};
+export const listAgentManagedTempOutputDirs = async () => {
+    const tempRoot = tmpdir();
+    try {
+        const entries = await readdir(tempRoot, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(AGENT_MANAGED_OUTPUT_DIR_PREFIX))
+            .map((entry) => join(tempRoot, entry.name));
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return [];
+        }
+        throw error;
+    }
+};
+export const writeJsonlAtomic = async (filePath, values) => {
+    await mkdir(dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const content = values.map((value) => JSON.stringify(value)).join("\n") + (values.length ? "\n" : "");
+    await writeFile(tempPath, content, "utf-8");
+    await rename(tempPath, filePath);
+};
+const removeLockIfStale = async (lockPath) => {
+    try {
+        const lockStat = await stat(lockPath);
+        if (Date.now() - lockStat.mtimeMs > AGENT_STATE_LOCK_STALE_MS) {
+            await rm(lockPath, { force: true });
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return true;
+        }
+        throw error;
+    }
+};
+const openAgentStateLock = async (lockPath) => {
+    let lockHandle;
+    try {
+        lockHandle = await open(lockPath, "wx");
+        await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`, "utf-8");
+        return lockHandle;
+    }
+    catch (error) {
+        if (lockHandle) {
+            await lockHandle.close().catch(() => undefined);
+            await rm(lockPath, { force: true }).catch(() => undefined);
+        }
+        throw error;
+    }
+};
+const runWithAgentStateLock = async (lockPath, lockHandle, operation) => {
+    try {
+        return await operation();
+    }
+    finally {
+        await lockHandle.close().catch(() => undefined);
+        await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+};
+export const withAgentStateLock = async (cwd, operation) => {
+    const normalizedCwd = resolve(cwd);
+    const stateDir = resolveAgentStateDir(normalizedCwd);
+    const lockPath = projectLockPath(normalizedCwd);
+    let lastError;
+    await mkdir(stateDir, { recursive: true });
+    for (let attempt = 0; attempt < AGENT_STATE_LOCK_RETRIES; attempt += 1) {
+        try {
+            const lockHandle = await openAgentStateLock(lockPath);
+            return await runWithAgentStateLock(lockPath, lockHandle, operation);
+        }
+        catch (error) {
+            if (!isFileExistsError(error)) {
+                throw error;
+            }
+            lastError = error;
+            await removeLockIfStale(lockPath);
+            await sleep(AGENT_STATE_LOCK_RETRY_MS);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(`Could not acquire agent state lock: ${lockPath}`);
+};
+export const tryWithAgentStateLock = async (cwd, operation) => {
+    const normalizedCwd = resolve(cwd);
+    const stateDir = resolveAgentStateDir(normalizedCwd);
+    const lockPath = projectLockPath(normalizedCwd);
+    await mkdir(stateDir, { recursive: true });
+    try {
+        const lockHandle = await openAgentStateLock(lockPath);
+        return {
+            acquired: true,
+            result: await runWithAgentStateLock(lockPath, lockHandle, operation),
+        };
+    }
+    catch (error) {
+        if (!isFileExistsError(error)) {
+            throw error;
+        }
+        if (!(await removeLockIfStale(lockPath))) {
+            return { acquired: false };
+        }
+    }
+    try {
+        const lockHandle = await openAgentStateLock(lockPath);
+        return {
+            acquired: true,
+            result: await runWithAgentStateLock(lockPath, lockHandle, operation),
+        };
+    }
+    catch (error) {
+        if (isFileExistsError(error)) {
+            return { acquired: false };
+        }
+        throw error;
+    }
+};
+export const pathExists = async (path) => {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return false;
+        }
+        return true;
+    }
+};
+export const readPathMtimeMs = async (path) => {
+    const pathStat = await stat(path);
+    return pathStat.mtimeMs;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allurereport/plugin-agent",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Allure Agent Plugin – AI-friendly markdown report generator",
   "keywords": [
     "agent",
@@ -27,16 +27,16 @@
     "build": "run clean && tsc --project ./tsconfig.json",
     "clean": "rimraf ./dist",
     "test": "rimraf ./out && vitest run",
-    "lint": "oxlint --import-plugin src test features stories",
-    "lint:fix": "oxlint --import-plugin --fix src test features stories"
+    "lint": "yarn run -T oxlint --import-plugin src test features stories",
+    "lint:fix": "yarn run -T oxlint --import-plugin --fix src test features stories"
   },
   "dependencies": {
-    "@allurereport/core-api": "3.10.0",
-    "@allurereport/plugin-api": "3.10.0",
+    "@allurereport/core-api": "3.12.0",
+    "@allurereport/plugin-api": "3.12.0",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@allurereport/reader-api": "3.10.0",
+    "@allurereport/reader-api": "3.12.0",
     "@types/node": "^20",
     "@vitest/runner": "^2",
     "allure-js-commons": "^3",