aienvmp 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.7
+
+- Added stale open intent warnings for long-running environment change plans.
+- Added stale handoff warnings when environment changes happen after the last recorded AI handoff.
+- Added optional `aienvmp handoff --record --actor <agent:id>` timeline entries.
+
+## 0.1.6
+
+- Added optional `sync --deep` / `scan --deep` read-only global tool inventory.
+- Kept the default scan lightweight while exposing deep inventory summaries to `AIENV.md`, `context`, `handoff`, and the dashboard.
+- Added parsers for npm global packages, pipx tools, uv tools, and Homebrew package versions.
+
 ## 0.1.5
 
 - Added machine-readable trust states for observed, planned, changed, review, verified, and stale environment facts.

package/README.md

@@ -18,6 +18,13 @@ Core loop: scan the env, give AI a preflight context, and hand off safe next ste
 npx aienvmp sync
 npx aienvmp context
 npx aienvmp handoff
+npx aienvmp handoff --record --actor agent:codex
+```
+
+Optional deeper read-only inventory:
+
+```bash
+npx aienvmp sync --deep
 ```
 
 ## Output
@@ -59,7 +66,8 @@ aienvmp doctor --ci       # strict CI check
 - simple by default
 - AI-first
 - lightweight
-- non-blocking unless strict mode is requested
+- one advisory engine, optional enforcement with `doctor --ci`
+- non-blocking unless strict mode is explicitly requested
 
 ## Development
 

package/ROADMAP.md

@@ -6,6 +6,7 @@
 
 - Strengthen trust states: observed, planned, changed, review, verified, stale
 - Detect multi-agent environment intent conflicts
+- Keep one advisory decision engine with optional strict enforcement
 - Stabilize `.aienvmp/manifest.json` and JSON command schemas
 - Keep `sync`, `context`, and `handoff` as the simple core flow
 - Improve the dashboard for 10-second human review
@@ -17,13 +18,11 @@
   - pyenv, uv, conda
   - mise, asdf
 - Global tool inventory:
-  - `npm -g`
-  - `pipx list`
-  - `uv tool list`
+  - richer summaries for `npm -g`, `pipx list`, `uv tool list`, and Homebrew
+  - optional `--deep` scanners for more toolchains
 - Conflict detection:
-  - stale unresolved intents
-  - recent runtime changes without a fresh handoff
   - package manager policy vs lockfile mismatch
+  - monorepo/project boundary aware intent targets
 - CI mode:
   - stable exit codes
   - GitHub Action example

package/package.json

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

package/src/cli.js

@@ -74,9 +74,9 @@ function printUsage() {
   console.log(`aienvmp - AI-first env map + lightweight runtime SBOM
 
 Usage:
-  aienvmp sync [--dir .] [--json] [--quiet]
+  aienvmp sync [--dir .] [--json] [--quiet] [--deep]
   aienvmp context [--dir .] [--json]
-  aienvmp handoff [--dir .] [--json]
+  aienvmp handoff [--dir .] [--json] [--record --actor agent:id]
 
 Common:
   aienvmp sync      update AIENV.md, manifest, ledger, intents, and dashboard
@@ -87,7 +87,7 @@ Common:
 
 Advanced:
   aienvmp init [--dir .]
-  aienvmp scan [--dir .]
+  aienvmp scan [--dir .] [--deep]
   aienvmp intent [--dir .] --actor agent:codex --action "install pnpm"
   aienvmp resolve [--dir .] --actor human:you --id <intent-id> [--status resolved|cancelled]
   aienvmp record [--dir .] --actor agent:codex --summary "updated .nvmrc" [--target node] [--before 20] [--after 24]

package/src/commands/context.js

@@ -24,6 +24,7 @@ export async function contextWorkspace(args) {
       runtimes: manifest.runtimes,
       packageManagers: manifest.packageManagers,
       containers: manifest.containers,
+      inventory: inventorySummary(manifest.inventory),
       projectHints: manifest.projectHints,
       warnings,
       policy,
@@ -36,6 +37,15 @@ export async function contextWorkspace(args) {
   console.log(renderContext(manifest, timeline, warnings, intents, policy));
 }
 
+function inventorySummary(inventory = {}) {
+  const tools = inventory.tools || {};
+  return {
+    mode: inventory.mode || "basic",
+    enabled: inventory.enabled === true,
+    groups: Object.fromEntries(Object.entries(tools).map(([name, items]) => [name, items.length]))
+  };
+}
+
 function contextDecision(warnings, intents) {
   const reviewRequired = warnings.length > 0 || intents.length > 0;
   return {

package/src/commands/handoff.js

@@ -1,9 +1,10 @@
 import { diagnose } from "../doctor.js";
-import { readJson } from "../fsutil.js";
+import { appendJsonLine, readJson } from "../fsutil.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
 import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderHandoff } from "../render.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+import { changedTrust } from "../trust.js";
 
 export async function handoffWorkspace(args) {
   const dir = workspaceDir(args);
@@ -14,6 +15,9 @@ export async function handoffWorkspace(args) {
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const handoff = buildHandoff(manifest, timeline, warnings, intents, policy);
+  if (args.record) {
+    await recordHandoff(timelinePath(dir), handoff, args.actor || "agent:unknown");
+  }
 
   if (args.json) {
     console.log(JSON.stringify(handoff, null, 2));
@@ -23,6 +27,19 @@ export async function handoffWorkspace(args) {
   return handoff;
 }
 
+async function recordHandoff(file, handoff, actor) {
+  const now = new Date();
+  await appendJsonLine(file, {
+    at: now.toISOString(),
+    actor,
+    type: "agent-handoff",
+    summary: `handoff ${handoff.status}`,
+    status: handoff.status,
+    warnings: handoff.warnings.map((warning) => warning.code),
+    trust: changedTrust(now, handoff.status !== "clear")
+  });
+}
+
 export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const reviewRequired = warnings.length > 0 || intents.length > 0;
   return {
@@ -35,6 +52,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
       python: manifest.runtimes?.python || manifest.runtimes?.python3 || "not detected",
       docker: manifest.containers?.docker ? "available" : "not detected"
     },
+    inventory: inventorySummary(manifest.inventory),
     policy: {
       node: policy.node || "not set",
       python: policy.python || "not set",
@@ -55,3 +73,12 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
       : "continue with project-local work; record intent before environment changes"
   };
 }
+
+function inventorySummary(inventory = {}) {
+  const tools = inventory.tools || {};
+  return {
+    mode: inventory.mode || "basic",
+    enabled: inventory.enabled === true,
+    groups: Object.fromEntries(Object.entries(tools).map(([name, items]) => [name, items.length]))
+  };
+}

package/src/commands/scan.js

@@ -11,7 +11,7 @@ export async function scanWorkspace(args) {
   if (previous && await exists(currentPath)) {
     await fs.copyFile(currentPath, previousManifestPath(dir));
   }
-  const manifest = await buildManifest(dir);
+  const manifest = await buildManifest(dir, { deep: args.deep });
   await writeJson(currentPath, manifest);
   const changes = diffManifests(previous, manifest);
   for (const change of changes) {

package/src/doctor.js

@@ -43,6 +43,8 @@ export function diagnose(manifest, context = {}) {
     });
   }
   warnings.push(...coordinationWarnings(context.intents || []));
+  warnings.push(...staleIntentWarnings(context.intents || []));
+  warnings.push(...handoffWarnings(context.timeline || []));
   return warnings;
 }
 
@@ -69,6 +71,30 @@ export function coordinationWarnings(intents = []) {
   return warnings;
 }
 
+export function staleIntentWarnings(intents = [], now = new Date(), maxAgeHours = 4) {
+  const warnings = [];
+  for (const intent of intents) {
+    if (!isStaleTimestamp(intent.at, now, maxAgeHours)) continue;
+    warnings.push({
+      code: "stale-open-intent",
+      target: intent.target || inferTarget(intent.action) || "",
+      message: `Open intent ${intent.id || ""} from ${intent.actor || "unknown"} is older than ${maxAgeHours} hours. Resolve it or confirm it before environment changes.`.replace(/\s+/g, " ").trim()
+    });
+  }
+  return warnings;
+}
+
+export function handoffWarnings(timeline = []) {
+  const lastEnvChange = [...timeline].reverse().find(isEnvironmentChange);
+  if (!lastEnvChange) return [];
+  const lastHandoff = [...timeline].reverse().find((item) => item.type === "agent-handoff");
+  if (lastHandoff && new Date(lastHandoff.at).getTime() >= new Date(lastEnvChange.at).getTime()) return [];
+  return [{
+    code: "handoff-stale",
+    message: "Environment changes were recorded after the last AI handoff. Run `aienvmp handoff --record --actor agent:id` before the next agent continues."
+  }];
+}
+
 function inferTarget(action = "") {
   const normalized = String(action).toLowerCase();
   for (const target of ["node", "python", "docker", "npm", "pnpm", "yarn", "uv", "pip", "pipx"]) {
@@ -76,3 +102,24 @@ function inferTarget(action = "") {
   }
   return "";
 }
+
+function isEnvironmentChange(item = {}) {
+  if (["runtime", "package-manager", "container"].includes(item.change?.scope)) return true;
+  if (item.type === "detected-change") return false;
+  const text = `${item.type || ""} ${item.target || ""} ${item.summary || ""} ${item.action || ""} ${item.change?.scope || ""} ${item.change?.key || ""}`.toLowerCase();
+  return [
+    "runtime",
+    "node",
+    "python",
+    "docker",
+    "package manager",
+    "package-manager",
+    "npm",
+    "pnpm",
+    "yarn",
+    "uv",
+    "pip",
+    "pipx",
+    "global"
+  ].some((token) => text.includes(token));
+}

package/src/inventory.js

@@ -0,0 +1,88 @@
+import { commandOutput } from "./shell.js";
+
+const MAX_ITEMS = 40;
+
+export async function scanGlobalInventory(options = {}) {
+  if (!options.deep) {
+    return {
+      mode: "basic",
+      enabled: false,
+      note: "Run `aienvmp sync --deep` to collect read-only global tool inventory."
+    };
+  }
+
+  return {
+    mode: "deep",
+    enabled: true,
+    note: "Read-only global tool inventory. Use for AI awareness, not enforcement.",
+    tools: compact({
+      npmGlobal: await scanNpmGlobal(),
+      pipx: await scanPipx(),
+      uvTools: await scanUvTools(),
+      brew: await scanBrew()
+    })
+  };
+}
+
+export async function scanNpmGlobal() {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const raw = await commandOutput(command, ["list", "-g", "--depth=0", "--json"], { timeout: 5000, maxBuffer: 2 * 1024 * 1024 });
+  return parseNpmGlobal(raw);
+}
+
+export async function scanPipx() {
+  const raw = await commandOutput("pipx", ["list", "--json"], { timeout: 5000, maxBuffer: 2 * 1024 * 1024 });
+  return parsePipx(raw);
+}
+
+export async function scanUvTools() {
+  const raw = await commandOutput("uv", ["tool", "list"], { timeout: 5000 });
+  return parseNameVersionLines(raw);
+}
+
+export async function scanBrew() {
+  if (process.platform === "win32") return [];
+  const raw = await commandOutput("brew", ["list", "--versions"], { timeout: 5000, maxBuffer: 2 * 1024 * 1024 });
+  return parseNameVersionLines(raw);
+}
+
+export function parseNpmGlobal(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return Object.entries(parsed.dependencies || {})
+      .slice(0, MAX_ITEMS)
+      .map(([name, value]) => ({ name, version: value.version || "unknown" }));
+  } catch {
+    return [];
+  }
+}
+
+export function parsePipx(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return Object.entries(parsed.venvs || {})
+      .slice(0, MAX_ITEMS)
+      .map(([name, value]) => ({
+        name,
+        version: value.metadata?.main_package?.package_version || "unknown"
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export function parseNameVersionLines(raw) {
+  return String(raw || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, MAX_ITEMS)
+    .map((line) => {
+      const [name, ...rest] = line.split(/\s+/);
+      return { name, version: rest.join(" ") || "unknown" };
+    });
+}
+
+function compact(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => Array.isArray(value) && value.length));
+}

package/src/manifest.js

@@ -4,8 +4,9 @@ import path from "node:path";
 import { commandOutput, commandVersion } from "./shell.js";
 import { exists } from "./fsutil.js";
 import { observedTrust } from "./trust.js";
+import { scanGlobalInventory } from "./inventory.js";
 
-export async function buildManifest(dir) {
+export async function buildManifest(dir, options = {}) {
   const now = new Date().toISOString();
   const manifest = {
     schemaName: "aienvmp.runtime-sbom",
@@ -13,7 +14,7 @@ export async function buildManifest(dir) {
     generatedAt: now,
     generatedBy: {
       name: "aienvmp",
-      command: "aienvmp sync"
+      command: options.deep ? "aienvmp sync --deep" : "aienvmp sync"
     },
     trust: observedTrust(new Date(now)),
     workspace: {
@@ -25,13 +26,14 @@ export async function buildManifest(dir) {
     packageManagers: await scanPackageManagers(),
     containers: await scanContainers(),
     projectHints: await scanProjectHints(dir),
+    inventory: await scanGlobalInventory({ deep: options.deep }),
     agentFiles: await scanAgentFiles(dir),
     agentProtocol: {
       sourceOfTruth: "AIENV.md",
       preflightCommand: "aienvmp context",
       handoffCommand: "aienvmp handoff",
-      intentCommand: "aienvmp intent --actor <agent:id> --action <planned-change>",
-      recordCommand: "aienvmp record --actor <agent:id> --summary <what-changed>",
+      intentCommand: "aienvmp intent --actor agent:id --action planned-change",
+      recordCommand: "aienvmp record --actor agent:id --summary what-changed",
       afterEnvironmentChange: ["aienvmp sync"],
       trustModel: {
         agentWritable: ["observed", "planned", "changed", "review", "stale"],
@@ -69,6 +71,13 @@ export async function buildManifest(dir) {
         docker: "docker --version",
         compose: "docker compose version or docker-compose --version"
       },
+      globalInventory: {
+        mode: "basic by default; deep only when requested",
+        npmGlobal: "npm list -g --depth=0 --json",
+        pipx: "pipx list --json",
+        uvTools: "uv tool list",
+        brew: "brew list --versions"
+      },
       projectHints: [
         ".nvmrc",
         ".python-version",

package/src/render.js

@@ -12,9 +12,10 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push("1. Run `aienvmp context`.");
   lines.push("2. Prefer project-local version files such as `.nvmrc`, `.python-version`, `mise.toml`, and `.tool-versions`.");
   lines.push("3. Ask the user before changing global environment state.");
-  lines.push("4. Record planned environment changes with `aienvmp intent --actor <agent:id> --action <planned-change>`.");
+  lines.push("4. Record planned environment changes with `aienvmp intent --actor agent:id --action planned-change`.");
   lines.push("5. After environment changes, run `aienvmp sync`.");
-  lines.push("6. Record what changed with `aienvmp record --actor <agent:id> --summary <what-changed>`.", "");
+  lines.push("6. Record what changed with `aienvmp record --actor agent:id --summary what-changed`.");
+  lines.push("7. At handoff, run `aienvmp handoff --record --actor agent:id`.", "");
   lines.push("## Current Policy", "");
   lines.push(...policyLines(policy));
   lines.push("- Enforcement: non-blocking by default; warnings require review but do not lock the machine.");
@@ -28,6 +29,8 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   pushMap(lines, "Runtimes", manifest.runtimes);
   pushMap(lines, "Package Managers", manifest.packageManagers);
   pushMap(lines, "Containers", manifest.containers);
+  lines.push("## Global Tool Inventory", "");
+  lines.push(...inventoryLines(manifest.inventory), "");
   lines.push("## Project Requirements And Hints", "");
   pushMap(lines, "Detected", manifest.projectHints);
   lines.push("## Drift And Warnings", "");
@@ -74,6 +77,7 @@ Before changing runtimes, package managers, Docker settings, global packages, or
 4. Record planned environment changes with \`aienvmp intent\`.
 5. After environment changes, run \`aienvmp sync\`.
 6. Record what changed with \`aienvmp record\`.
+7. At handoff, run \`aienvmp handoff --record --actor agent:id\`.
 
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
@@ -91,6 +95,7 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     `Node: ${manifest.runtimes.node || "not detected"}`,
     `Python: ${manifest.runtimes.python || manifest.runtimes.python3 || "not detected"}`,
     `Docker: ${manifest.containers.docker ? "available" : "not detected"}`,
+    `Inventory: ${manifest.inventory?.mode || "basic"}${manifest.inventory?.enabled ? " enabled" : " disabled"}`,
     `Policy Node: ${policy.node || "not set"}`,
     `Policy Python: ${policy.python || "not set"}`,
     `Policy Package Manager: ${policy.packageManager || "not set"}`,
@@ -99,9 +104,10 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "- Ask the user before global runtime, package manager, Docker, or global package changes.",
     "- Treat policy mismatches as review-required, not as permission to break ongoing operations.",
     "- Prefer project-local version files and local environments.",
-    "- Before planned env changes, run `aienvmp intent --actor <agent:id> --action <planned-change>`.",
+    "- Before planned env changes, run `aienvmp intent --actor agent:id --action planned-change`.",
     "- After env changes, run `aienvmp sync`.",
-    "- Then run `aienvmp record --actor <agent:id> --summary <what-changed>`.",
+    "- Then run `aienvmp record --actor agent:id --summary what-changed`.",
+    "- Before handing work to another AI, run `aienvmp handoff --record --actor agent:id`.",
     "",
     "Warnings:",
     ...(warnings.length ? warnings.map((w) => `- ${w.message}`) : ["- none"]),
@@ -128,6 +134,7 @@ export function renderHandoff(handoff) {
     `- Node: ${handoff.safeRuntime.node}`,
     `- Python: ${handoff.safeRuntime.python}`,
     `- Docker: ${handoff.safeRuntime.docker}`,
+    `- Inventory: ${handoff.inventory?.mode || "basic"}${handoff.inventory?.enabled ? " enabled" : " disabled"}`,
     "",
     "Open intents:",
     ...(handoff.openIntents.length ? handoff.openIntents.map((i) => `- ${i.actor}: ${i.action}${i.target ? ` (${i.target})` : ""}`) : ["- none"]),
@@ -203,6 +210,9 @@ const {manifest,timeline,warnings,intents,policy}=JSON.parse(document.getElement
 function esc(s){return String(s).replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('"','&quot;')}
 const entries=o=>Object.entries(o||{});
 const rows=o=>entries(o).map(([k,v])=>\`<tr><th>\${esc(k)}</th><td><code>\${esc(String(v))}</code></td></tr>\`).join('')||'<tr><td colspan="2">None detected</td></tr>';
+const inventoryGroups=manifest.inventory?.tools||{};
+const inventoryCount=Object.values(inventoryGroups).reduce((sum,items)=>sum+(Array.isArray(items)?items.length:0),0);
+const inventoryHtml=manifest.inventory?.enabled?('<table>'+Object.entries(inventoryGroups).map(([k,v])=>\`<tr><th>\${esc(k)}</th><td><code>\${Array.isArray(v)?v.length:0} tools</code></td></tr>\`).join('')+'</table>'):'<div class="okline">Deep global inventory is off. Run <code>aienvmp sync --deep</code> when an AI needs global tool awareness.</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'};
@@ -246,6 +256,7 @@ document.getElementById('app').innerHTML=\`
     \${card('Package Managers',\`<span class="pill">\${entries(manifest.packageManagers).length} found</span>\`,\`<table>\${rows(manifest.packageManagers)}</table>\`)}
     \${card('Containers',manifest.containers?.docker?'<span class="pill">available</span>':'<span class="pill off">not detected</span>',\`<table>\${rows(manifest.containers)}</table>\`)}
     \${card('Project Hints',\`<span class="pill">\${entries(manifest.projectHints).length} hints</span>\`,\`<table>\${rows(manifest.projectHints)}</table>\`)}
+    \${card('Global Inventory',manifest.inventory?.enabled?'<span class="pill">deep</span>':'<span class="pill off">basic</span>',inventoryHtml)}
   </div>
   <aside>
     \${card('Environment Health',warnings.length?'<span class="pill warn">attention</span>':'<span class="pill">clear</span>',warnHtml)}
@@ -304,6 +315,17 @@ function contextLines(manifest, warnings, intents) {
   ];
 }
 
+function inventoryLines(inventory = {}) {
+  if (!inventory.enabled) return ["- Mode: basic", "- Deep global inventory is disabled. Run `aienvmp sync --deep` when needed."];
+  const groups = Object.entries(inventory.tools || {});
+  if (!groups.length) return ["- Mode: deep", "- No global tools detected by optional scanners."];
+  const lines = ["- Mode: deep"];
+  for (const [name, items] of groups) {
+    lines.push(`- ${name}: ${items.length} tools`);
+  }
+  return lines;
+}
+
 function policyLines(policy) {
   const lines = [];
   if (policy.node) lines.push(`- Node version policy: ${policy.node}`);

package/src/shell.js

@@ -15,10 +15,11 @@ export async function commandVersion(command, args = ["--version"]) {
   }
 }
 
-export async function commandOutput(command, args = []) {
+export async function commandOutput(command, args = [], options = {}) {
   try {
     const { stdout } = await execFileAsync(command, args, {
-      timeout: 2500,
+      timeout: options.timeout || 2500,
+      maxBuffer: options.maxBuffer || 1024 * 1024,
       windowsHide: true
     });
     return stdout.trim();