aienvmp 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.14
+
+- Added `aienvmp plan` for read-only AI environment action plans.
+- Added optional `aienvmp plan --write` artifacts at `.aienvmp/plan.json` and `.aienvmp/plan.md`.
+- Kept plan output advisory-only with review gates instead of automatic fixes.
+
+## 0.1.13
+
+- Added `recommendedActions` to AI handoff output.
+- Added a Recommended Actions dashboard card for human review.
+- Reused the same advisory action engine across context, doctor, handoff, and dashboard.
+
 ## 0.1.12
 
 - Added AI-readable `recommendedActions` to `context --json` and `doctor --json`.

package/README.md

@@ -17,6 +17,7 @@ Core loop: scan the env, give AI a preflight context, and hand off safe next ste
 ```bash
 npx aienvmp sync
 npx aienvmp context
+npx aienvmp plan
 npx aienvmp handoff
 npx aienvmp handoff --record --actor agent:codex
 ```
@@ -56,7 +57,8 @@ npx aienvmp snippet agents
 aienvmp sync              # update env map, light SBOM, ledger, dashboard
 aienvmp context           # AI preflight brief
 aienvmp context --json    # machine-readable AI decision context + recommended actions
-aienvmp handoff           # next-agent handoff summary
+aienvmp plan              # read-only AI action plan, no automatic fixes
+aienvmp handoff           # next-agent handoff summary + recommended actions
 aienvmp intent            # record a planned env change
 aienvmp record            # record what changed
 aienvmp doctor --ci       # strict CI check

package/package.json

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

package/src/cli.js

@@ -11,6 +11,7 @@ import { resolveWorkspace } from "./commands/resolve.js";
 import { syncWorkspace } from "./commands/sync.js";
 import { snippetWorkspace } from "./commands/snippet.js";
 import { handoffWorkspace } from "./commands/handoff.js";
+import { planWorkspace } from "./commands/plan.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -26,7 +27,8 @@ const commands = new Map([
   ["resolve", resolveWorkspace],
   ["sync", syncWorkspace],
   ["snippet", snippetWorkspace],
-  ["handoff", handoffWorkspace]
+  ["handoff", handoffWorkspace],
+  ["plan", planWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -77,11 +79,13 @@ Usage:
   aienvmp sync [--dir .] [--json] [--quiet] [--deep] [--security]
   aienvmp context [--dir .] [--json]
   aienvmp handoff [--dir .] [--json] [--record --actor agent:id]
+  aienvmp plan [--dir .] [--json] [--write]
 
 Common:
   aienvmp sync      update AIENV.md, manifest, ledger, intents, and dashboard
   aienvmp context   print the AI preflight brief
   aienvmp handoff   print the next-agent handoff summary
+  aienvmp plan      print a read-only AI environment action plan
   aienvmp snippet   print an AGENTS.md pointer snippet
   aienvmp dash      regenerate/open the lightweight dashboard
 

package/src/commands/dash.js

@@ -7,6 +7,7 @@ import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { dashboardPath, intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderDashboard } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { recommendedActions } from "../actions.js";
 
 export async function dashWorkspace(args) {
   const dir = workspaceDir(args);
@@ -16,7 +17,7 @@ export async function dashWorkspace(args) {
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
-  const html = renderDashboard(manifest, timeline, warnings, intents, policy);
+  const html = renderDashboard({ ...manifest, recommendedActions: recommendedActions(manifest, { warnings, intents }) }, timeline, warnings, intents, policy);
   const out = dashboardPath(dir);
   await fs.mkdir(path.dirname(out), { recursive: true });
   await fs.writeFile(out, html, "utf8");

package/src/commands/handoff.js

@@ -5,6 +5,7 @@ import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.
 import { renderHandoff } from "../render.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { changedTrust } from "../trust.js";
+import { recommendedActions } from "../actions.js";
 
 export async function handoffWorkspace(args) {
   const dir = workspaceDir(args);
@@ -42,6 +43,7 @@ async function recordHandoff(file, handoff, actor) {
 
 export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const reviewRequired = warnings.length > 0 || intents.length > 0;
+  const actions = recommendedActions(manifest, { warnings, intents });
   return {
     status: reviewRequired ? "review-required" : "clear",
     trust: manifest.trust || {},
@@ -63,6 +65,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
     },
     openIntents: intents.slice(-5).reverse(),
     warnings,
+    recommendedActions: actions,
     recentChanges: timeline.slice(-5).reverse(),
     mustNotDo: [
       "do not change global runtimes without user approval",

package/src/commands/plan.js

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import { diagnose } from "../doctor.js";
+import { readJson, writeJson } from "../fsutil.js";
+import { loadPolicy, policyWarnings } from "../policy.js";
+import { intentsPath, manifestPath, planJsonPath, planMdPath, timelinePath, workspaceDir } from "../paths.js";
+import { renderPlan } from "../render.js";
+import { recommendedActions } from "../actions.js";
+import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+
+export async function planWorkspace(args) {
+  const dir = workspaceDir(args);
+  const manifest = await readJson(manifestPath(dir));
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
+  const timeline = await readTimeline(timelinePath(dir));
+  const intents = openIntents(await readJsonl(intentsPath(dir)));
+  const policy = await loadPolicy(dir);
+  const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
+  const plan = buildPlan(manifest, warnings, intents, policy);
+
+  if (args.write) {
+    await writeJson(planJsonPath(dir), plan);
+    await fs.writeFile(planMdPath(dir), renderPlan(plan), "utf8");
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(plan, null, 2));
+  } else {
+    console.log(renderPlan(plan));
+  }
+  return plan;
+}
+
+export function buildPlan(manifest, warnings = [], intents = [], policy = {}) {
+  const actions = recommendedActions(manifest, { warnings, intents });
+  const status = warnings.length || intents.length ? "review-required" : "clear";
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    status,
+    workspace: manifest.workspace || {},
+    trust: manifest.trust || {},
+    policy: {
+      node: policy.node || "not set",
+      python: policy.python || "not set",
+      packageManager: policy.packageManager || "not set",
+      runtimeChanges: policy.runtimeChanges || "ask-first",
+      globalInstalls: policy.globalInstalls || "ask-first"
+    },
+    recommendedActions: actions,
+    reviewGates: reviewGates(warnings, intents, manifest.security),
+    warnings,
+    openIntents: intents.slice(-5).reverse(),
+    security: {
+      mode: manifest.security?.mode || "basic",
+      enabled: manifest.security?.enabled === true,
+      summary: manifest.security?.summary || { total: 0, critical: 0, high: 0, moderate: 0, low: 0, info: 0 },
+      topPackages: manifest.security?.topPackages || []
+    },
+    notes: [
+      "This plan is read-only.",
+      "Ask the user before global runtime, package manager, Docker, or global package changes.",
+      "Prefer project-local version files and local environments."
+    ]
+  };
+}
+
+function reviewGates(warnings, intents, security = {}) {
+  const gates = [];
+  if (warnings.length) gates.push("Review warnings before changing the environment.");
+  if (intents.length) gates.push("Resolve or coordinate open intents before overlapping environment changes.");
+  const summary = security.summary || {};
+  if (security.enabled && (Number(summary.critical || 0) > 0 || Number(summary.high || 0) > 0)) {
+    gates.push("Review high or critical vulnerability remediation before dependency or deployment changes.");
+  }
+  if (!gates.length) gates.push("No blocking gates detected; continue project-local work and record intent before environment changes.");
+  return gates;
+}

package/src/paths.js

@@ -28,6 +28,14 @@ export function dashboardPath(dir) {
   return path.join(stateDir(dir), "dashboard.html");
 }
 
+export function planJsonPath(dir) {
+  return path.join(stateDir(dir), "plan.json");
+}
+
+export function planMdPath(dir) {
+  return path.join(stateDir(dir), "plan.md");
+}
+
 export function aiEnvPath(dir) {
   return path.join(dir, "AIENV.md");
 }

package/src/render.js

@@ -149,6 +149,9 @@ export function renderHandoff(handoff) {
     "Warnings:",
     ...(handoff.warnings.length ? handoff.warnings.map((w) => `- ${w.message}`) : ["- none"]),
     "",
+    "Recommended actions:",
+    ...(handoff.recommendedActions?.length ? handoff.recommendedActions.map((item) => `- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`) : ["- none"]),
+    "",
     "Recent changes:",
     ...(handoff.recentChanges.length ? handoff.recentChanges.map((t) => `- ${formatTimeline(t)}`) : ["- none"]),
     "",
@@ -161,6 +164,31 @@ export function renderHandoff(handoff) {
   return lines.join("\n");
 }
 
+export function renderPlan(plan) {
+  const lines = [
+    "# AI Environment Plan",
+    "",
+    `Status: ${plan.status}`,
+    `Generated: ${plan.generatedAt}`,
+    `Workspace: ${plan.workspace?.path || "unknown"}`,
+    "",
+    "Purpose: read-only review plan for AI agents and humans. It does not install, remove, upgrade, downgrade, or lock anything.",
+    "",
+    "Recommended actions:",
+    ...(plan.recommendedActions.length
+      ? plan.recommendedActions.map((item) => `- [${item.priority}] ${item.category}: ${item.summary}${item.command ? ` (${item.command})` : ""}`)
+      : ["- none"]),
+    "",
+    "Review gates:",
+    ...plan.reviewGates.map((item) => `- ${item}`),
+    "",
+    "Warnings:",
+    ...(plan.warnings.length ? plan.warnings.map((warning) => `- [${warning.code}] ${warning.message}`) : ["- none"]),
+    ""
+  ];
+  return lines.join("\n");
+}
+
 export function renderDashboard(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const data = JSON.stringify({ manifest, timeline, warnings, intents, policy });
   return `<!doctype html>
@@ -234,6 +262,8 @@ const warnHtml=warnings.length?'<div class="warnings">'+warnings.map(w=>\`<div c
 const timelineHtml=timeline.length?'<div class="timeline">'+timeline.slice(-8).reverse().map(t=>\`<div class="event"><time>\${esc(t.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(t.actor||'system')}</b> \${esc(timelineLabel(t))}</div></div>\`).join('')+'</div>':'<div class="okline">No previous environment changes recorded.</div>';
 const intentsHtml=intents.length?'<div class="timeline">'+intents.slice(-6).reverse().map(i=>\`<div class="event"><time>\${esc(i.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(i.actor)}</b> plans \${esc(i.action)}</div></div>\`).join('')+'</div>':'<div class="okline">No pending agent intents recorded.</div>';
 const policyHtml=entries(policy).length?\`<table>\${rows(policy)}</table>\`:'<div class="okline">No explicit version policy set.</div>';
+const actions=manifest.recommendedActions||[];
+const actionsHtml=actions.length?'<div class="timeline">'+actions.slice(0,6).map(a=>\`<div class="event"><time>\${esc(a.priority)}</time><div><b>\${esc(a.category)}</b> \${esc(a.summary)}\${a.command?\`<div class="path">\${esc(a.command)}</div>\`:''}</div></div>\`).join('')+'</div>':'<div class="okline">No recommended actions. Continue project-local work.</div>';
 const card=(title,badge,body)=>\`<section class="card"><div class="card-head"><h2>\${title}</h2>\${badge||''}</div>\${body}</section>\`;
 const reviewRequired=warnings.length>0||intents.length>0;
 const recentChanges=timeline.slice(-8).length;
@@ -273,6 +303,8 @@ document.getElementById('app').innerHTML=\`
     \${card('Security Summary',sec.enabled?'<span class="pill warn">security</span>':'<span class="pill off">basic</span>',securityHtml)}
   </div>
   <aside>
+    \${card('Recommended Actions','<span class="pill">'+actions.length+' actions</span>',actionsHtml)}
+    <div style="height:14px"></div>
     \${card('Environment Health',warnings.length?'<span class="pill warn">attention</span>':'<span class="pill">clear</span>',warnHtml)}
     <div style="height:14px"></div>
     \${card('Version Policy','<span class="pill">'+entries(policy).length+' rules</span>',policyHtml)}