aienvmp 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

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,6 +57,7 @@ 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 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.13",
+  "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/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

@@ -164,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>