aienvmp 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.15
+
+- Added dashboard links for written AI plan artifacts.
+- Added `write-plan` support to the GitHub Action so CI can emit read-only plan outputs.
+- Updated the GitHub Action example to show the sync, plan, and doctor flow.
+
+## 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
 ```
@@ -35,6 +36,8 @@ AIENV.md
 .aienvmp/manifest.json
 .aienvmp/intents.jsonl
 .aienvmp/timeline.jsonl
+.aienvmp/plan.json
+.aienvmp/plan.md
 .aienvmp/dashboard.html
 ```
 
@@ -56,6 +59,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/action.yml

@@ -11,6 +11,10 @@ inputs:
     description: Fail when doctor reports warnings
     required: false
     default: "false"
+  write-plan:
+    description: Write read-only AI plan artifacts
+    required: false
+    default: "true"
 
 runs:
   using: composite
@@ -19,6 +23,13 @@ runs:
       shell: bash
       run: node "$GITHUB_ACTION_PATH/bin/aienvmp.js" sync --dir "${{ inputs.directory }}" --quiet
 
+    - name: Write AI plan
+      shell: bash
+      run: |
+        if [ "${{ inputs.write-plan }}" = "true" ]; then
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" plan --dir "${{ inputs.directory }}" --write --json
+        fi
+
     - name: Doctor
       shell: bash
       run: |

package/examples/github-action.yml

@@ -13,4 +13,5 @@ jobs:
       - uses: soovwv/aienvmp@main
         with:
           directory: "."
+          write-plan: "true"
           strict: "false"

package/package.json

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

@@ -2,9 +2,9 @@ import fs from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { diagnose } from "../doctor.js";
-import { readJson } from "../fsutil.js";
+import { exists, readJson } from "../fsutil.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
-import { dashboardPath, intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
+import { dashboardPath, intentsPath, manifestPath, planJsonPath, planMdPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderDashboard } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
 import { recommendedActions } from "../actions.js";
@@ -17,7 +17,8 @@ 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, recommendedActions: recommendedActions(manifest, { warnings, intents }) }, timeline, warnings, intents, policy);
+  const planArtifacts = await detectedPlanArtifacts(dir);
+  const html = renderDashboard({ ...manifest, recommendedActions: recommendedActions(manifest, { warnings, intents }), planArtifacts }, timeline, warnings, intents, policy);
   const out = dashboardPath(dir);
   await fs.mkdir(path.dirname(out), { recursive: true });
   await fs.writeFile(out, html, "utf8");
@@ -26,6 +27,15 @@ export async function dashWorkspace(args) {
   return { dashboard: out };
 }
 
+async function detectedPlanArtifacts(dir) {
+  const json = planJsonPath(dir);
+  const markdown = planMdPath(dir);
+  return {
+    json: await exists(json) ? ".aienvmp/plan.json" : "",
+    markdown: await exists(markdown) ? ".aienvmp/plan.md" : ""
+  };
+}
+
 function openFile(file) {
   if (process.platform === "win32") {
     execFile("cmd", ["/c", "start", "", file], { windowsHide: true });

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>
@@ -227,7 +252,7 @@ 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 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 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');
@@ -239,6 +264,8 @@ const intentsHtml=intents.length?'<div class="timeline">'+intents.slice(-6).reve
 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 plan=manifest.planArtifacts||{};
+const planHtml=plan.markdown||plan.json?\`<table><tr><th>Markdown</th><td>\${plan.markdown?'<a href="plan.md">plan.md</a>':'not written'}</td></tr><tr><th>JSON</th><td>\${plan.json?'<a href="plan.json">plan.json</a>':'not written'}</td></tr></table>\`:'<div class="okline">No plan artifacts yet. Run <code>aienvmp plan --write</code>.</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;
@@ -280,6 +307,8 @@ document.getElementById('app').innerHTML=\`
   <aside>
     \${card('Recommended Actions','<span class="pill">'+actions.length+' actions</span>',actionsHtml)}
     <div style="height:14px"></div>
+    \${card('AI Plan Artifacts',plan.markdown||plan.json?'<span class="pill">written</span>':'<span class="pill off">not written</span>',planHtml)}
+    <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)}