aienvmp 0.1.10 → 0.1.12

package/BUGFIXES.md

@@ -28,6 +28,12 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: test command used `/bin/zsh -lc` to load login shell PATH.
 - Verification: remote test detected Node `v25.3.0`, npm `11.11.0`, and completed `aienvmp sync`.
 
+### Security summaries lacked remediation hints
+
+- Issue: AI agents could see vulnerable package names but not enough bounded detail to plan the next dependency update.
+- Fix: npm and Python security summaries now include fix versions and advisory references when scanners provide them.
+- Verification: parser tests cover npm remediation objects and pip-audit advisory ids; Windows and macOS tarball tests completed `sync --security`.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.12
+
+- Added AI-readable `recommendedActions` to `context --json` and `doctor --json`.
+- Added concise recommended actions to text context and doctor output.
+- Kept recommendations advisory-only; strict failure still requires `doctor --ci`.
+
+## 0.1.11
+
+- Added bounded remediation details to security summaries, including fix versions and advisory references.
+- Surfaced remediation hints in `AIENV.md` and the dashboard so AI agents can plan safer dependency updates.
+- Kept security scanning read-only and opt-in.
+
 ## 0.1.10
 
 - Added optional `pip-audit` JSON parsing for Python security summaries.

package/README.md

@@ -55,7 +55,7 @@ npx aienvmp snippet agents
 ```bash
 aienvmp sync              # update env map, light SBOM, ledger, dashboard
 aienvmp context           # AI preflight brief
-aienvmp context --json    # machine-readable AI decision context
+aienvmp context --json    # machine-readable AI decision context + recommended actions
 aienvmp handoff           # next-agent handoff summary
 aienvmp intent            # record a planned env change
 aienvmp record            # record what changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {

package/src/actions.js

@@ -0,0 +1,87 @@
+export function recommendedActions(manifest = {}, context = {}) {
+  const warnings = context.warnings || [];
+  const intents = context.intents || [];
+  const actions = [];
+
+  if (isStaleWarning(warnings)) {
+    actions.push(action("sync-snapshot", "high", "sync", "Refresh the environment snapshot before changing runtimes or package managers.", "aienvmp sync"));
+  }
+
+  if (intents.length) {
+    actions.push(action("review-open-intents", "high", "coordination", "Review or resolve open environment intents before another agent changes the environment.", "aienvmp context --json"));
+  }
+
+  if (warnings.some((warning) => warning.code === "conflicting-open-intents")) {
+    actions.push(action("coordinate-agents", "high", "coordination", "Multiple agents are planning changes to the same environment target. Coordinate with the user before proceeding."));
+  }
+
+  actions.push(...securityActions(manifest.security));
+
+  if (hasRuntimePolicyWarning(warnings)) {
+    actions.push(action("review-version-policy", "medium", "runtime", "Detected runtime or package manager policy drift. Prefer project-local version files and ask before global changes."));
+  }
+
+  if (warnings.some((warning) => warning.code === "handoff-stale")) {
+    actions.push(action("record-handoff", "medium", "handoff", "Record an AI handoff after environment changes so the next agent starts with current context.", "aienvmp handoff --record --actor agent:id"));
+  }
+
+  if (!actions.length) {
+    actions.push(action("continue-project-local", "low", "workflow", "Continue with project-local work. Record intent before environment changes.", "aienvmp intent --actor agent:id --action planned-change"));
+  }
+
+  return dedupeActions(actions).slice(0, 8);
+}
+
+function securityActions(security = {}) {
+  if (!security.enabled) return [];
+
+  const summary = security.summary || {};
+  const highRisk = Number(summary.critical || 0) > 0 || Number(summary.high || 0) > 0;
+  const packages = (security.topPackages || []).slice(0, 5);
+  if (!highRisk && !packages.length) return [];
+
+  const packageHints = packages.map((pkg) => {
+    const fix = pkg.fixVersions?.length ? `fix ${pkg.fixVersions.slice(0, 2).join(", ")}` : pkg.fixAvailable ? "fix available" : "review required";
+    return `${pkg.name} (${pkg.severity}, ${fix})`;
+  });
+
+  return [action(
+    "review-security-remediation",
+    highRisk ? "high" : "medium",
+    "security",
+    packageHints.length
+      ? `Review vulnerable packages before dependency or deployment changes: ${packageHints.join("; ")}.`
+      : "Review vulnerability summary before dependency or deployment changes.",
+    "aienvmp context --json"
+  )];
+}
+
+function action(id, priority, category, summary, command = "") {
+  return { id, priority, category, summary, command };
+}
+
+function dedupeActions(actions) {
+  const seen = new Set();
+  return actions.filter((item) => {
+    if (seen.has(item.id)) return false;
+    seen.add(item.id);
+    return true;
+  });
+}
+
+function isStaleWarning(warnings) {
+  return warnings.some((warning) => warning.code === "manifest-stale" || warning.code === "stale-open-intent");
+}
+
+function hasRuntimePolicyWarning(warnings) {
+  return warnings.some((warning) => [
+    "node-version-mismatch",
+    "python-version-mismatch",
+    "mixed-node-lockfiles",
+    "python-missing",
+    "docker-missing",
+    "policy-node-mismatch",
+    "policy-python-mismatch",
+    "policy-package-manager-mismatch"
+  ].includes(warning.code));
+}

package/src/commands/context.js

@@ -4,6 +4,7 @@ import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderContext } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { recommendedActions } from "../actions.js";
 
 export async function contextWorkspace(args) {
   const dir = workspaceDir(args);
@@ -14,10 +15,12 @@ export async function contextWorkspace(args) {
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const decision = contextDecision(warnings, intents);
+  const actions = recommendedActions(manifest, { warnings, intents });
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
       decision,
+      recommendedActions: actions,
       trust: manifest.trust || {},
       guidance: decision,
       workspace: manifest.workspace,
@@ -35,7 +38,7 @@ export async function contextWorkspace(args) {
     }, null, 2));
     return;
   }
-  console.log(renderContext(manifest, timeline, warnings, intents, policy));
+  console.log(renderContext(manifest, timeline, warnings, intents, policy, actions));
 }
 
 function securitySummary(security = {}) {

package/src/commands/doctor.js

@@ -3,6 +3,7 @@ import { readJson } from "../fsutil.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { recommendedActions } from "../actions.js";
 
 export async function doctorWorkspace(args) {
   const dir = workspaceDir(args);
@@ -12,13 +13,15 @@ export async function doctorWorkspace(args) {
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
+  const actions = recommendedActions(manifest, { warnings, intents });
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "warning" : "ok",
       trust: manifest.trust || {},
       policy,
       openIntentCount: intents.length,
-      warnings
+      warnings,
+      recommendedActions: actions
     }, null, 2));
     if (args.ci && warnings.length) {
       process.exitCode = 1;
@@ -32,6 +35,10 @@ export async function doctorWorkspace(args) {
   for (const warning of warnings) {
     console.log(`[${warning.code}] ${warning.message}`);
   }
+  console.log("recommended actions:");
+  for (const item of actions) {
+    console.log(`- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`);
+  }
   console.log("doctor: warnings are non-blocking by default; pass --ci to fail automation.");
   if (args.ci) {
     process.exitCode = 1;

package/src/render.js

@@ -84,7 +84,7 @@ Before changing runtimes, package managers, Docker settings, global packages, or
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
 
-export function renderContext(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
+export function renderContext(manifest, timeline = [], warnings = [], intents = [], policy = {}, recommendedActions = []) {
   const status = warnings.length ? "review-required" : "clear";
   const next = warnings.length ? "Review warnings before changing the environment." : "Continue with project-local work. Record intent before environment changes.";
   return [
@@ -115,6 +115,9 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "Warnings:",
     ...(warnings.length ? warnings.map((w) => `- ${w.message}`) : ["- none"]),
     "",
+    "Recommended actions:",
+    ...(recommendedActions.length ? recommendedActions.map((item) => `- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`) : ["- none"]),
+    "",
     "Open intents:",
     ...(intents.length ? intents.slice(-5).reverse().map((i) => `- ${i.actor}: ${i.action}`) : ["- none"]),
     "",
@@ -220,7 +223,9 @@ const inventoryHtml=manifest.inventory?.enabled?('<table>'+Object.entries(invent
 const sec=manifest.security||{};
 const secSummary=sec.summary||{total:0,critical:0,high:0,moderate:0,low:0,info:0};
 const secPackages=sec.topPackages||[];
-const securityHtml=sec.enabled?\`<table><tr><th>Total</th><td><code>\${esc(secSummary.total||0)}</code></td></tr><tr><th>Critical</th><td><code>\${esc(secSummary.critical||0)}</code></td></tr><tr><th>High</th><td><code>\${esc(secSummary.high||0)}</code></td></tr><tr><th>Moderate</th><td><code>\${esc(secSummary.moderate||0)}</code></td></tr><tr><th>Low</th><td><code>\${esc(secSummary.low||0)}</code></td></tr></table>\${secPackages.length?'<div class="timeline">'+secPackages.slice(0,5).map(p=>\`<div class="event"><time>\${esc(p.severity)}</time><div><b>\${esc(p.name)}</b> \${p.fixAvailable?'fix available':'review required'}</div></div>\`).join('')+'</div>':'<div class="okline" style="margin-top:10px">No vulnerable packages reported.</div>'}\`:'<div class="okline">Security scan is off. Run <code>aienvmp sync --security</code> for read-only vulnerability summary.</div>';
+const securityFix=p=>p.fixVersions?.length?\`fix \${p.fixVersions.slice(0,3).join(', ')}\`:(p.fixAvailable?'fix available':'review required');
+const securityRefs=p=>p.advisories?.length?\` · \${p.advisories.map(a=>a.id||a.title).filter(Boolean).slice(0,2).join(', ')}\`:'';
+const securityHtml=sec.enabled?\`<table><tr><th>Total</th><td><code>\${esc(secSummary.total||0)}</code></td></tr><tr><th>Critical</th><td><code>\${esc(secSummary.critical||0)}</code></td></tr><tr><th>High</th><td><code>\${esc(secSummary.high||0)}</code></td></tr><tr><th>Moderate</th><td><code>\${esc(secSummary.moderate||0)}</code></td></tr><tr><th>Low</th><td><code>\${esc(secSummary.low||0)}</code></td></tr></table>\${secPackages.length?'<div class="timeline">'+secPackages.slice(0,5).map(p=>\`<div class="event"><time>\${esc(p.severity)}</time><div><b>\${esc(p.name)}</b> \${esc(securityFix(p))}\${esc(securityRefs(p))}</div></div>\`).join('')+'</div>':'<div class="okline" style="margin-top:10px">No vulnerable packages reported.</div>'}\`:'<div class="okline">Security scan is off. Run <code>aienvmp sync --security</code> for read-only vulnerability summary.</div>';
 const change=c=>c.type==='changed'?\`\${c.scope} \${c.key}: \${c.before} -> \${c.after}\`:\`\${c.scope} \${c.key}: \${c.type} \${c.after||c.before}\`;
 const timelineLabel=t=>t.change?change(t.change):(t.summary||t.action||t.type||'recorded change');
 const agentNames={agents:'Codex',claude:'Claude',gemini:'Gemini'};
@@ -350,12 +355,21 @@ function securityLines(security = {}) {
   if (packages.length) {
     lines.push("- Top vulnerable packages:");
     for (const pkg of packages.slice(0, 8)) {
-      lines.push(`  - ${pkg.name}: ${pkg.severity}; ${pkg.fixAvailable ? "fix available" : "review required"}`);
+      lines.push(`  - ${pkg.name}: ${pkg.severity}; ${securityPackageNote(pkg)}`);
     }
   }
   return lines;
 }
 
+function securityPackageNote(pkg) {
+  const fix = pkg.fixVersions?.length ? `fix ${pkg.fixVersions.slice(0, 3).join(", ")}` : pkg.fixAvailable ? "fix available" : "review required";
+  const advisories = (pkg.advisories || [])
+    .map((item) => item.id || item.title)
+    .filter(Boolean)
+    .slice(0, 2);
+  return advisories.length ? `${fix}; advisories ${advisories.join(", ")}` : fix;
+}
+
 function policyLines(policy) {
   const lines = [];
   if (policy.node) lines.push(`- Node version policy: ${policy.node}`);

package/src/security.js

@@ -80,12 +80,18 @@ export function parseNpmAudit(raw) {
     const vulnerabilities = parsed.vulnerabilities || {};
     const severityCounts = Object.fromEntries(SEVERITIES.map((severity) => [severity, Number(metadata.vulnerabilities?.[severity] || 0)]));
     const total = Number(metadata.vulnerabilities?.total || Object.values(severityCounts).reduce((sum, value) => sum + value, 0));
-    const vulnerablePackages = Object.entries(vulnerabilities).slice(0, 20).map(([name, value]) => ({
-      name,
-      severity: value.severity || "unknown",
-      viaCount: Array.isArray(value.via) ? value.via.length : 0,
-      fixAvailable: Boolean(value.fixAvailable)
-    }));
+    const vulnerablePackages = Object.entries(vulnerabilities).slice(0, 20).map(([name, value]) => {
+      const fixVersions = npmFixVersions(value.fixAvailable);
+      const advisories = npmAdvisories(value.via);
+      return {
+        name,
+        severity: value.severity || "unknown",
+        viaCount: Array.isArray(value.via) ? value.via.length : 0,
+        fixAvailable: hasFixAvailable(value.fixAvailable),
+        fixVersions,
+        advisories
+      };
+    });
     return {
       available: true,
       summary: { total, ...severityCounts },
@@ -109,7 +115,8 @@ export function parsePipAudit(raw) {
         severity: "unknown",
         viaCount: dependency.vulns.length,
         fixAvailable: dependency.vulns.some((vuln) => Array.isArray(vuln.fix_versions) && vuln.fix_versions.length),
-        fixVersions: unique(dependency.vulns.flatMap((vuln) => vuln.fix_versions || [])).slice(0, 5)
+        fixVersions: unique(dependency.vulns.flatMap((vuln) => vuln.fix_versions || [])).slice(0, 5),
+        advisories: pipAdvisories(dependency.vulns)
       }));
     const total = vulnerablePackages.reduce((sum, pkg) => sum + pkg.viaCount, 0);
     return {
@@ -151,3 +158,38 @@ function unavailable(scanner, reason) {
 function unique(items) {
   return [...new Set(items.filter(Boolean))];
 }
+
+function hasFixAvailable(value) {
+  if (typeof value === "boolean") return value;
+  return Boolean(value && typeof value === "object");
+}
+
+function npmFixVersions(value) {
+  if (!value || typeof value !== "object") return [];
+  return unique([value.version]).slice(0, 5);
+}
+
+function npmAdvisories(via = []) {
+  if (!Array.isArray(via)) return [];
+  return via
+    .filter((item) => item && typeof item === "object")
+    .map((item) => ({
+      id: String(item.source || item.id || item.cve || item.name || "").trim(),
+      title: String(item.title || "").trim(),
+      url: String(item.url || "").trim(),
+      severity: item.severity || "unknown"
+    }))
+    .filter((item) => item.id || item.title || item.url)
+    .slice(0, 5);
+}
+
+function pipAdvisories(vulns = []) {
+  return vulns
+    .map((vuln) => ({
+      id: String(vuln.id || vuln.aliases?.[0] || "").trim(),
+      aliases: Array.isArray(vuln.aliases) ? vuln.aliases.slice(0, 5) : [],
+      fixVersions: Array.isArray(vuln.fix_versions) ? vuln.fix_versions.slice(0, 5) : []
+    }))
+    .filter((item) => item.id || item.aliases.length || item.fixVersions.length)
+    .slice(0, 5);
+}