autoremediator 0.2.1 → 0.3.0

package/dist/{chunk-DQKT2CUG.js → chunk-URM53GSJ.js}

@@ -1,7 +1,7 @@
 // src/remediation/pipeline.ts
 import { generateText as generateText2 } from "ai";
 import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import semver4 from "semver";
 
 // src/platform/config.ts
@@ -574,7 +574,7 @@ var findFixedVersionTool = tool4({
 // src/remediation/tools/apply-version-bump.ts
 import { tool as tool5 } from "ai";
 import { z as z5 } from "zod";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { readFileSync as readFileSync3, writeFileSync } from "fs";
 import { execa as execa2 } from "execa";
 import semver3 from "semver";
@@ -585,7 +585,11 @@ import { join as join3 } from "path";
 var DEFAULT_POLICY = {
   allowMajorBumps: false,
   denyPackages: [],
-  allowPackages: []
+  allowPackages: [],
+  constraints: {
+    directDependenciesOnly: false,
+    preferVersionBump: false
+  }
 };
 function loadPolicy(cwd, explicitPath) {
   const candidate = explicitPath ?? join3(cwd, ".autoremediator.json");
@@ -595,7 +599,11 @@ function loadPolicy(cwd, explicitPath) {
     return {
       allowMajorBumps: parsed.allowMajorBumps ?? DEFAULT_POLICY.allowMajorBumps,
       denyPackages: parsed.denyPackages ?? DEFAULT_POLICY.denyPackages,
-      allowPackages: parsed.allowPackages ?? DEFAULT_POLICY.allowPackages
+      allowPackages: parsed.allowPackages ?? DEFAULT_POLICY.allowPackages,
+      constraints: {
+        directDependenciesOnly: parsed.constraints?.directDependenciesOnly ?? DEFAULT_POLICY.constraints?.directDependenciesOnly ?? false,
+        preferVersionBump: parsed.constraints?.preferVersionBump ?? DEFAULT_POLICY.constraints?.preferVersionBump ?? false
+      }
     };
   } catch {
     return DEFAULT_POLICY;
@@ -609,6 +617,45 @@ function isPackageAllowed(policy, packageName) {
   return true;
 }
 
+// src/platform/repo-lock.ts
+import { mkdir, rm } from "fs/promises";
+import { join as join4 } from "path";
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function acquireRepoLock(cwd, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 15e3;
+  const retryDelayMs = options.retryDelayMs ?? 125;
+  const lockRoot = join4(cwd, ".autoremediator", "locks");
+  const lockPath = join4(cwd, ".autoremediator", "locks", "remediation.lock");
+  const startedAt = Date.now();
+  await mkdir(lockRoot, { recursive: true });
+  while (true) {
+    try {
+      await mkdir(lockPath, { recursive: false });
+      return {
+        lockPath,
+        release: async () => {
+          await rm(lockPath, { recursive: true, force: true });
+        }
+      };
+    } catch {
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Timed out waiting for repository lock at ${lockPath}.`);
+      }
+      await sleep(retryDelayMs);
+    }
+  }
+}
+async function withRepoLock(cwd, fn, options) {
+  const lock = await acquireRepoLock(cwd, options);
+  try {
+    return await fn();
+  } finally {
+    await lock.release();
+  }
+}
+
 // src/remediation/tools/apply-version-bump.ts
 var applyVersionBumpTool = tool5({
   description: "Update package.json to use the safe version of a vulnerable package and run the project's package manager install. In dry-run mode, only reports what would change.",
@@ -634,7 +681,7 @@ var applyVersionBumpTool = tool5({
   }) => {
     const pm = packageManager ?? detectPackageManager(cwd);
     const commands = getPackageManagerCommands(pm);
-    const pkgPath = join4(cwd, "package.json");
+    const pkgPath = join5(cwd, "package.json");
     const policy = loadPolicy(cwd, policyPath);
     if (!isPackageAllowed(policy, packageName)) {
       return {
@@ -702,46 +749,18 @@ var applyVersionBumpTool = tool5({
         message: `[DRY RUN] Would update ${depField}.${packageName}: "${currentRange}" \u2192 "${newRange}", then run ${installCmd}${skipTests ? "" : ` and ${testCmd}`}.`
       };
     }
-    pkgJson[depField][packageName] = newRange;
-    writeFileSync(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
-    try {
-      const [installCmd, ...installArgs] = commands.installPreferOffline;
-      await execa2(installCmd, installArgs, {
-        cwd,
-        stdio: "pipe"
-      });
-    } catch (err) {
-      pkgJson[depField][packageName] = currentRange;
+    return withRepoLock(cwd, async () => {
+      pkgJson[depField][packageName] = newRange;
       writeFileSync(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        packageName,
-        strategy: "version-bump",
-        fromVersion,
-        toVersion,
-        applied: false,
-        dryRun: false,
-        message: `${commands.installPreferOffline.join(" ")} failed after updating "${packageName}" to ${toVersion}. Reverted. Error: ${message}`
-      };
-    }
-    if (!skipTests) {
       try {
-        const [testCmd, ...testArgs] = commands.test;
-        await execa2(testCmd, testArgs, {
+        const [installCmd, ...installArgs] = commands.installPreferOffline;
+        await execa2(installCmd, installArgs, {
           cwd,
           stdio: "pipe"
         });
       } catch (err) {
         pkgJson[depField][packageName] = currentRange;
         writeFileSync(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
-        try {
-          const [rollbackCmd, ...rollbackArgs] = commands.installPreferOffline;
-          await execa2(rollbackCmd, rollbackArgs, {
-            cwd,
-            stdio: "pipe"
-          });
-        } catch {
-        }
         const message = err instanceof Error ? err.message : String(err);
         return {
           packageName,
@@ -750,27 +769,57 @@ var applyVersionBumpTool = tool5({
           toVersion,
           applied: false,
           dryRun: false,
-          message: `${commands.test.join(" ")} failed after upgrading "${packageName}" to ${toVersion}. Rolled back to ${currentRange}. Error: ${message}`
+          message: `${commands.installPreferOffline.join(" ")} failed after updating "${packageName}" to ${toVersion}. Reverted. Error: ${message}`
         };
       }
-    }
-    return {
-      packageName,
-      strategy: "version-bump",
-      fromVersion,
-      toVersion,
-      applied: true,
-      dryRun: false,
-      message: `Successfully upgraded "${packageName}" from ${fromVersion} to ${toVersion}, ran ${commands.installPreferOffline.join(" ")}${skipTests ? "" : `, and passed ${commands.test.join(" ")}`}.`
-    };
+      if (!skipTests) {
+        try {
+          const [testCmd, ...testArgs] = commands.test;
+          await execa2(testCmd, testArgs, {
+            cwd,
+            stdio: "pipe"
+          });
+        } catch (err) {
+          pkgJson[depField][packageName] = currentRange;
+          writeFileSync(pkgPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf8");
+          try {
+            const [rollbackCmd, ...rollbackArgs] = commands.installPreferOffline;
+            await execa2(rollbackCmd, rollbackArgs, {
+              cwd,
+              stdio: "pipe"
+            });
+          } catch {
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          return {
+            packageName,
+            strategy: "version-bump",
+            fromVersion,
+            toVersion,
+            applied: false,
+            dryRun: false,
+            message: `${commands.test.join(" ")} failed after upgrading "${packageName}" to ${toVersion}. Rolled back to ${currentRange}. Error: ${message}`
+          };
+        }
+      }
+      return {
+        packageName,
+        strategy: "version-bump",
+        fromVersion,
+        toVersion,
+        applied: true,
+        dryRun: false,
+        message: `Successfully upgraded "${packageName}" from ${fromVersion} to ${toVersion}, ran ${commands.installPreferOffline.join(" ")}${skipTests ? "" : `, and passed ${commands.test.join(" ")}`}.`
+      };
+    });
   }
 });
 
 // src/remediation/tools/fetch-package-source.ts
 import { tool as tool6 } from "ai";
 import { z as z6 } from "zod";
-import { mkdir, readdir, readFile, rm } from "fs/promises";
-import { join as join5 } from "path";
+import { mkdir as mkdir2, readdir, readFile, rm as rm2 } from "fs/promises";
+import { join as join6 } from "path";
 import { execa as execa3 } from "execa";
 var fetchPackageSourceTool = tool6({
   description: "Download package tarball from npm and extract source files for CVE analysis. Supports custom file patterns (default: *.js, *.ts).",
@@ -787,23 +836,23 @@ var fetchPackageSourceTool = tool6({
     filePatterns
   }) => {
     const tempBaseDir = `/tmp/autoremediator-pkg-${Date.now()}`;
-    const extractDir = join5(tempBaseDir, "out");
+    const extractDir = join6(tempBaseDir, "out");
     try {
       const npmUrl = `https://registry.npmjs.org/${packageName}/-/${packageName.split("/").pop()}-${version}.tgz`;
-      await mkdir(tempBaseDir, { recursive: true });
-      const tarballPath = join5(tempBaseDir, "package.tgz");
+      await mkdir2(tempBaseDir, { recursive: true });
+      const tarballPath = join6(tempBaseDir, "package.tgz");
       await execa3("curl", ["-L", "-o", tarballPath, npmUrl]);
-      await mkdir(extractDir, { recursive: true });
+      await mkdir2(extractDir, { recursive: true });
       await execa3("tar", ["-xzf", tarballPath, "-C", extractDir]);
       const extractedContents = await readdir(extractDir);
-      const packageRootDir = extractedContents.includes("package") ? join5(extractDir, "package") : extractDir;
+      const packageRootDir = extractedContents.includes("package") ? join6(extractDir, "package") : extractDir;
       const sourceCode = {};
       async function walkDir(dir, relativeBase) {
         try {
           const files = await readdir(dir, { withFileTypes: true });
           for (const file of files) {
-            const fullPath = join5(dir, file.name);
-            const relPath = join5(relativeBase, file.name);
+            const fullPath = join6(dir, file.name);
+            const relPath = join6(relativeBase, file.name);
             if (file.isDirectory()) {
               if (![
                 "node_modules",
@@ -860,7 +909,7 @@ var fetchPackageSourceTool = tool6({
         error: `Failed to fetch and extract package ${packageName}@${version}: ${message}`
       };
     } finally {
-      await rm(tempBaseDir, { recursive: true, force: true });
+      await rm2(tempBaseDir, { recursive: true, force: true });
     }
   }
 });
@@ -1076,9 +1125,9 @@ function generateUnifiedDiff(original, fixed, filePath) {
 import { tool as tool8 } from "ai";
 import { z as z8 } from "zod";
 import { existsSync as existsSync3 } from "fs";
-import { mkdir as mkdir2, mkdtemp, readFile as readFile2, rm as rm2, writeFile } from "fs/promises";
+import { mkdir as mkdir3, mkdtemp, readFile as readFile2, rm as rm3, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { execa as execa4 } from "execa";
 var applyPatchFileTool = tool8({
   description: "Write generated patch file and apply it using package-manager-native patch flow when available, falling back to patch-package when needed.",
@@ -1126,7 +1175,7 @@ var applyPatchFileTool = tool8({
         };
       }
       const patchFileName = buildPatchFileName(packageName, vulnerableVersion);
-      const patchFilePath = join6(cwd, patchesDir, patchFileName);
+      const patchFilePath = join7(cwd, patchesDir, patchFileName);
       if (dryRun) {
         return {
           success: true,
@@ -1139,66 +1188,68 @@ var applyPatchFileTool = tool8({
           patchPath: patchFilePath
         };
       }
-      const patchesDirPath = join6(cwd, patchesDir);
-      await mkdir2(patchesDirPath, { recursive: true });
-      await writeFile(patchFilePath, selectedPatch, "utf8");
-      let validationResult;
-      const patchMode = await resolvePatchMode(pm, cwd);
-      const applyResult = patchMode === "patch-package" ? await configurePatchPackagePostinstall(cwd, pm) : await applyNativePatch({
-        cwd,
-        packageName,
-        vulnerableVersion,
-        patchContent: selectedPatch,
-        patchMode
-      });
-      if (!applyResult.success) {
-        return {
-          success: false,
+      return withRepoLock(cwd, async () => {
+        const patchesDirPath = join7(cwd, patchesDir);
+        await mkdir3(patchesDirPath, { recursive: true });
+        await writeFile(patchFilePath, selectedPatch, "utf8");
+        let validationResult;
+        const patchMode = await resolvePatchMode(pm, cwd);
+        const applyResult = patchMode === "patch-package" ? await configurePatchPackagePostinstall(cwd, pm) : await applyNativePatch({
+          cwd,
           packageName,
           vulnerableVersion,
-          applied: false,
-          dryRun: false,
-          message: applyResult.error,
-          patchFilePath,
-          patchPath: patchFilePath,
-          patchMode,
-          postinstallConfigured: patchMode === "patch-package" ? false : void 0,
-          error: applyResult.error
-        };
-      }
-      if (validateWithTests) {
-        validationResult = await validatePatchWithTests(cwd, pm);
-        if (!validationResult.passed) {
-          const validationError = "Patch validation failed after apply; patch marked unresolved.";
+          patchContent: selectedPatch,
+          patchMode
+        });
+        if (!applyResult.success) {
           return {
             success: false,
             packageName,
             vulnerableVersion,
             applied: false,
             dryRun: false,
-            message: validationError,
+            message: applyResult.error,
             patchFilePath,
             patchPath: patchFilePath,
             patchMode,
-            postinstallConfigured: patchMode === "patch-package",
-            validation: validationResult,
-            error: validationError
+            postinstallConfigured: patchMode === "patch-package" ? false : void 0,
+            error: applyResult.error
           };
         }
-      }
-      return {
-        success: true,
-        packageName,
-        vulnerableVersion,
-        applied: true,
-        dryRun: false,
-        message: `Patch applied successfully for ${packageName}@${vulnerableVersion}.`,
-        patchFilePath,
-        patchPath: patchFilePath,
-        patchMode,
-        postinstallConfigured: patchMode === "patch-package",
-        validation: validationResult
-      };
+        if (validateWithTests) {
+          validationResult = await validatePatchWithTests(cwd, pm);
+          if (!validationResult.passed) {
+            const validationError = "Patch validation failed after apply; patch marked unresolved.";
+            return {
+              success: false,
+              packageName,
+              vulnerableVersion,
+              applied: false,
+              dryRun: false,
+              message: validationError,
+              patchFilePath,
+              patchPath: patchFilePath,
+              patchMode,
+              postinstallConfigured: patchMode === "patch-package",
+              validation: validationResult,
+              error: validationError
+            };
+          }
+        }
+        return {
+          success: true,
+          packageName,
+          vulnerableVersion,
+          applied: true,
+          dryRun: false,
+          message: `Patch applied successfully for ${packageName}@${vulnerableVersion}.`,
+          patchFilePath,
+          patchPath: patchFilePath,
+          patchMode,
+          postinstallConfigured: patchMode === "patch-package",
+          validation: validationResult
+        };
+      });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       return {
@@ -1233,7 +1284,7 @@ function buildPatchFileName(packageName, vulnerableVersion) {
   return `${safeName}+${vulnerableVersion}.patch`;
 }
 async function configurePatchPackagePostinstall(cwd, packageManager) {
-  const pkgJsonPath = join6(cwd, "package.json");
+  const pkgJsonPath = join7(cwd, "package.json");
   let pkgJson;
   try {
     pkgJson = JSON.parse(await readFile2(pkgJsonPath, "utf8"));
@@ -1297,8 +1348,8 @@ ${createResult.stderr}`);
       error: `Could not determine native patch directory for ${packageSpec}.`
     };
   }
-  const tempPatchDir = await mkdtemp(join6(tmpdir(), "autoremediator-native-patch-"));
-  const tempPatchFile = join6(tempPatchDir, "change.patch");
+  const tempPatchDir = await mkdtemp(join7(tmpdir(), "autoremediator-native-patch-"));
+  const tempPatchFile = join7(tempPatchDir, "change.patch");
   try {
     await writeFile(tempPatchFile, patchContent, "utf8");
     await execa4("patch", ["-p1", "-i", tempPatchFile], {
@@ -1317,7 +1368,7 @@ ${createResult.stderr}`);
       error: `Failed to apply native patch for ${packageSpec}: ${err instanceof Error ? err.message : String(err)}`
     };
   } finally {
-    await rm2(tempPatchDir, { recursive: true, force: true });
+    await rm3(tempPatchDir, { recursive: true, force: true });
   }
   return { success: true };
 }
@@ -1389,7 +1440,8 @@ async function runRemediationPipeline(cveId, options = {}) {
   }
   const cwd = options.cwd ?? process.cwd();
   const packageManager = options.packageManager ?? detectPackageManager(cwd);
-  const dryRun = options.dryRun ?? false;
+  const preview = options.preview ?? false;
+  const dryRun = (options.dryRun ?? false) || preview;
   const skipTests = options.skipTests ?? true;
   const policyPath = options.policyPath ?? "";
   const patchesDir = options.patchesDir || "./patches";
@@ -1408,6 +1460,14 @@ async function runRemediationPipeline(cveId, options = {}) {
   const vulnerablePackages = [];
   let cveDetails = null;
   let agentSteps = 0;
+  const applyVersionBumpToolForRun = preview ? {
+    ...applyVersionBumpTool,
+    execute: async (input) => applyVersionBumpTool.execute({ ...input, dryRun: true })
+  } : applyVersionBumpTool;
+  const applyPatchFileToolForRun = preview ? {
+    ...applyPatchFileTool,
+    execute: async (input) => applyPatchFileTool.execute({ ...input, dryRun: true })
+  } : applyPatchFileTool;
   const result = await generateText2({
     model,
     system: systemPrompt,
@@ -1417,10 +1477,10 @@ async function runRemediationPipeline(cveId, options = {}) {
       "check-inventory": checkInventoryTool,
       "check-version-match": checkVersionMatchTool,
       "find-fixed-version": findFixedVersionTool,
-      "apply-version-bump": applyVersionBumpTool,
+      "apply-version-bump": applyVersionBumpToolForRun,
       "fetch-package-source": fetchPackageSourceTool,
       "generate-patch": generatePatchTool,
-      "apply-patch-file": applyPatchFileTool
+      "apply-patch-file": applyPatchFileToolForRun
     },
     maxSteps: 25,
     onStepFinish(stepResult) {
@@ -1463,13 +1523,19 @@ async function runRemediationPipeline(cveId, options = {}) {
     vulnerablePackages,
     results: collectedResults,
     agentSteps,
-    summary: result.text
+    summary: result.text,
+    correlation: {
+      requestId: options.requestId,
+      sessionId: options.sessionId,
+      parentRunId: options.parentRunId
+    }
   };
 }
 async function runLocalRemediationPipeline(cveId, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const packageManager = options.packageManager ?? detectPackageManager(cwd);
-  const dryRun = options.dryRun ?? false;
+  const preview = options.preview ?? false;
+  const dryRun = (options.dryRun ?? false) || preview;
   const skipTests = options.skipTests ?? true;
   const policyPath = options.policyPath ?? "";
   const collectedResults = [];
@@ -1489,7 +1555,12 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
       vulnerablePackages,
       results: collectedResults,
       agentSteps,
-      summary: `Local mode failed at lookup-cve: ${normalizedId} not found in OSV or GitHub advisory data.`
+      summary: `Local mode failed at lookup-cve: ${normalizedId} not found in OSV or GitHub advisory data.`,
+      correlation: {
+        requestId: options.requestId,
+        sessionId: options.sessionId,
+        parentRunId: options.parentRunId
+      }
     };
   }
   cveDetails = osvDetails ?? {
@@ -1510,7 +1581,12 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
       vulnerablePackages,
       results: collectedResults,
       agentSteps,
-      summary: `Local mode lookup succeeded but no npm affected packages were found for ${normalizedId}.`
+      summary: `Local mode lookup succeeded but no npm affected packages were found for ${normalizedId}.`,
+      correlation: {
+        requestId: options.requestId,
+        sessionId: options.sessionId,
+        parentRunId: options.parentRunId
+      }
     };
   }
   const inventory = await checkInventoryTool.execute({ cwd, packageManager });
@@ -1522,7 +1598,12 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
       vulnerablePackages,
       results: collectedResults,
       agentSteps,
-      summary: `Local mode failed at check-inventory: ${inventory.error}`
+      summary: `Local mode failed at check-inventory: ${inventory.error}`,
+      correlation: {
+        requestId: options.requestId,
+        sessionId: options.sessionId,
+        parentRunId: options.parentRunId
+      }
     };
   }
   const installedPackages = inventory.packages ?? [];
@@ -1612,11 +1693,16 @@ async function runLocalRemediationPipeline(cveId, options = {}) {
     vulnerablePackages,
     results: collectedResults,
     agentSteps,
-    summary: `Local mode completed: vulnerable=${vulnerablePackages.length}, applied=${appliedCount}, dryRun=${dryRunCount}, unresolved=${unresolvedCount}`
+    summary: `Local mode completed: vulnerable=${vulnerablePackages.length}, applied=${appliedCount}, dryRun=${dryRunCount}, unresolved=${unresolvedCount}`,
+    correlation: {
+      requestId: options.requestId,
+      sessionId: options.sessionId,
+      parentRunId: options.parentRunId
+    }
   };
 }
 function loadOrchestrationPrompt(ctx) {
-  const promptPath = join7(process.cwd(), ".github", "instructions", "orchestration.instructions.md");
+  const promptPath = join8(process.cwd(), ".github", "instructions", "orchestration.instructions.md");
   if (!existsSync4(promptPath)) {
     return `You are autoremediator, an agentic security remediation system for Node.js package dependencies.
 Working directory: ${ctx.cwd}
@@ -1810,10 +1896,16 @@ function uniqueCveIds(findings) {
 
 // src/platform/evidence.ts
 import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
-import { join as join8 } from "path";
-function createEvidenceLog(cwd, cveIds) {
+import { join as join9 } from "path";
+function createEvidenceLog(cwd, cveIds, context = {}) {
   return {
-    runId: `${Date.now()}`,
+    runId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    requestId: context.requestId,
+    sessionId: context.sessionId,
+    parentRunId: context.parentRunId,
+    actor: context.actor,
+    source: context.source,
+    idempotencyKey: context.idempotencyKey,
     cveIds,
     cwd,
     startedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1834,21 +1926,163 @@ function finalizeEvidence(log) {
   return log;
 }
 function writeEvidenceLog(cwd, log) {
-  const dir = join8(cwd, ".autoremediator", "evidence");
+  const dir = join9(cwd, ".autoremediator", "evidence");
   mkdirSync(dir, { recursive: true });
-  const filePath = join8(dir, `${log.runId}.json`);
+  const filePath = join9(dir, `${log.runId}.json`);
   writeFileSync2(filePath, JSON.stringify(log, null, 2) + "\n", "utf8");
   return filePath;
 }
 
+// src/platform/idempotency.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync9, writeFileSync as writeFileSync3 } from "fs";
+import { join as join10 } from "path";
+var DEFAULT_INDEX = {
+  schemaVersion: "1.0",
+  entries: {}
+};
+function indexFilePath(cwd) {
+  return join10(cwd, ".autoremediator", "state", "idempotency.json");
+}
+function entryKey(idempotencyKey, cveId) {
+  return `${idempotencyKey}::${cveId.toUpperCase()}`;
+}
+function loadIndex(cwd) {
+  const filePath = indexFilePath(cwd);
+  if (!existsSync5(filePath)) return DEFAULT_INDEX;
+  try {
+    const parsed = JSON.parse(readFileSync9(filePath, "utf8"));
+    if (parsed && parsed.schemaVersion === "1.0" && parsed.entries) {
+      return parsed;
+    }
+    return DEFAULT_INDEX;
+  } catch {
+    return DEFAULT_INDEX;
+  }
+}
+function saveIndex(cwd, index) {
+  const filePath = indexFilePath(cwd);
+  mkdirSync2(join10(cwd, ".autoremediator", "state"), { recursive: true });
+  writeFileSync3(filePath, JSON.stringify(index, null, 2) + "\n", "utf8");
+}
+function readIdempotentReport(cwd, idempotencyKey, cveId) {
+  const index = loadIndex(cwd);
+  const key = entryKey(idempotencyKey, cveId);
+  return index.entries[key]?.report;
+}
+function storeIdempotentReport(cwd, idempotencyKey, cveId, report) {
+  const index = loadIndex(cwd);
+  const key = entryKey(idempotencyKey, cveId);
+  index.entries[key] = {
+    key: idempotencyKey,
+    cveId: cveId.toUpperCase(),
+    report,
+    savedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  saveIndex(cwd, index);
+}
+
 // src/api.ts
+function buildRequestId() {
+  return `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function resolveCorrelationContext(options) {
+  return {
+    requestId: options.requestId ?? buildRequestId(),
+    sessionId: options.sessionId,
+    parentRunId: options.parentRunId
+  };
+}
+function resolveProvenanceContext(options) {
+  return {
+    actor: options.actor,
+    source: options.source ?? "sdk"
+  };
+}
+function resolveConstraints(options, cwd) {
+  const policy = loadPolicy(cwd, options.policyPath);
+  return {
+    directDependenciesOnly: options.constraints?.directDependenciesOnly ?? policy.constraints?.directDependenciesOnly ?? false,
+    preferVersionBump: options.constraints?.preferVersionBump ?? policy.constraints?.preferVersionBump ?? false
+  };
+}
+function enforceConstraints(report, constraints) {
+  const indirectPackages = new Set(
+    report.vulnerablePackages.filter((vp) => vp.installed.type === "indirect").map((vp) => vp.installed.name)
+  );
+  const nextResults = report.results.map((result) => {
+    if (constraints.directDependenciesOnly && indirectPackages.has(result.packageName)) {
+      return {
+        ...result,
+        strategy: "none",
+        applied: false,
+        message: `Constraint blocked remediation for indirect dependency "${result.packageName}".`
+      };
+    }
+    if (constraints.preferVersionBump && result.strategy === "patch-file") {
+      return {
+        ...result,
+        strategy: "none",
+        applied: false,
+        message: `Constraint prefers version-bump and rejected patch-file remediation for "${result.packageName}".`
+      };
+    }
+    return result;
+  });
+  return {
+    ...report,
+    results: nextResults,
+    constraints
+  };
+}
 async function remediate(cveId, options = {}) {
   if (!/^CVE-\d{4}-\d+$/i.test(cveId)) {
     throw new Error(
       `Invalid CVE ID: "${cveId}". Expected format: CVE-YYYY-NNNNN (e.g. CVE-2021-23337).`
     );
   }
-  return runRemediationPipeline(cveId.toUpperCase(), options);
+  const cwd = options.cwd ?? process.cwd();
+  const constraints = resolveConstraints(options, cwd);
+  const provenance = resolveProvenanceContext(options);
+  const correlation = resolveCorrelationContext(options);
+  if (options.resume && options.idempotencyKey) {
+    const cached = readIdempotentReport(cwd, options.idempotencyKey, cveId.toUpperCase());
+    if (cached) {
+      return {
+        ...cached,
+        summary: `${cached.summary} (resumed from idempotency cache)`,
+        correlation,
+        provenance,
+        constraints,
+        resumedFromCache: true
+      };
+    }
+  }
+  const report = await runRemediationPipeline(cveId.toUpperCase(), {
+    ...options,
+    ...correlation,
+    constraints
+  });
+  const constrainedReport = enforceConstraints(report, constraints);
+  const finalReport = {
+    ...constrainedReport,
+    correlation,
+    provenance,
+    constraints,
+    resumedFromCache: false
+  };
+  if (options.idempotencyKey && !options.dryRun && !options.preview) {
+    storeIdempotentReport(cwd, options.idempotencyKey, cveId.toUpperCase(), finalReport);
+  }
+  return {
+    ...finalReport
+  };
+}
+async function planRemediation(cveId, options = {}) {
+  return remediate(cveId, {
+    ...options,
+    preview: true,
+    dryRun: true
+  });
 }
 async function remediateFromScan(inputPath, options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -1857,7 +2091,15 @@ async function remediateFromScan(inputPath, options = {}) {
   const findings = parseScanInput(inputPath, format);
   const cveIds = uniqueCveIds(findings);
   const policy = loadPolicy(cwd, options.policyPath);
-  const evidence = createEvidenceLog(cwd, cveIds);
+  const correlation = resolveCorrelationContext(options);
+  const provenance = resolveProvenanceContext(options);
+  const constraints = resolveConstraints(options, cwd);
+  const evidence = createEvidenceLog(cwd, cveIds, {
+    ...correlation,
+    actor: provenance.actor,
+    source: provenance.source,
+    idempotencyKey: options.idempotencyKey
+  });
   addEvidenceStep(evidence, "scan.parse", { inputPath, format }, { findingCount: findings.length, cveCount: cveIds.length });
   const reports = [];
   const errors = [];
@@ -1868,7 +2110,11 @@ async function remediateFromScan(inputPath, options = {}) {
       addEvidenceStep(evidence, "remediate.start", { cveId });
       const report = await remediate(cveId, {
         ...options,
-        patchesDir
+        patchesDir,
+        ...correlation,
+        actor: provenance.actor,
+        source: provenance.source,
+        constraints
       });
       report.results = report.results.filter((r) => isPackageAllowed(policy, r.packageName));
       for (const result of report.results) {
@@ -1923,7 +2169,11 @@ async function remediateFromScan(inputPath, options = {}) {
     evidenceFile,
     patchFileCount,
     patchValidationFailures: patchValidationFailures.length > 0 ? patchValidationFailures : void 0,
-    patchStorageDir: patchFileCount > 0 ? patchesDir : void 0
+    patchStorageDir: patchFileCount > 0 ? patchesDir : void 0,
+    correlation,
+    provenance,
+    constraints,
+    idempotencyKey: options.idempotencyKey
   };
 }
 function toCiSummary(report) {
@@ -1943,7 +2193,11 @@ function toCiSummary(report) {
     evidenceFile: report.evidenceFile,
     patchFileCount: report.patchFileCount || 0,
     patchValidationFailures: report.patchValidationFailures,
-    patchStorageDir: report.patchStorageDir
+    patchStorageDir: report.patchStorageDir,
+    correlation: report.correlation,
+    provenance: report.provenance,
+    constraints: report.constraints,
+    idempotencyKey: report.idempotencyKey
   };
 }
 function ciExitCode(summary) {
@@ -1953,8 +2207,9 @@ function ciExitCode(summary) {
 export {
   runRemediationPipeline,
   remediate,
+  planRemediation,
   remediateFromScan,
   toCiSummary,
   ciExitCode
 };
-//# sourceMappingURL=chunk-DQKT2CUG.js.map
+//# sourceMappingURL=chunk-URM53GSJ.js.map